---
title: Environment Artifact
description: Environment Artifact protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# Environment Artifact Format Protocol (v0)

Defines the immutable envelope produced by `objectstack compile` and consumed

by ObjectOS at boot. The artifact carries everything an ObjectOS instance

needs to hydrate an environment kernel without reading control-plane DB rows

directly.

## Boundary

- **Artifact (this schema):** environment metadata + inlined function code +

plugin/driver requirements. Immutable, content-addressable via `commitId`

and `checksum`.

- **Deployment Config (NOT in this schema):** business DB coordinates,

credentials, environment identity, secrets. Injected at runtime.

See [content/docs/concepts/north-star.mdx](content/docs/concepts/north-star.mdx) §6.3 for the runtime-inputs

boundary, and [ROADMAP.md](ROADMAP.md) M1 for the milestone definition.

## Storage / Distribution

v0 stores the full payload inline. Future revisions may swap `metadata` /

`functions` for a `payloadRef` that points at out-of-band storage (S3,

signed URL). The envelope shape preserves room for that indirection without

a breaking schema bump.

<Callout type="info">
**Source:** `packages/spec/src/system/environment-artifact.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { EnvironmentArtifact, EnvironmentArtifactChecksum, EnvironmentArtifactFunction, EnvironmentArtifactFunctionLanguageEnum, EnvironmentArtifactHashAlgorithmEnum, EnvironmentArtifactManifest, EnvironmentArtifactMetadata, EnvironmentArtifactPayloadRef, EnvironmentArtifactRequirement } from '@objectstack/spec/system';
import type { EnvironmentArtifact, EnvironmentArtifactChecksum, EnvironmentArtifactFunction, EnvironmentArtifactFunctionLanguageEnum, EnvironmentArtifactHashAlgorithmEnum, EnvironmentArtifactManifest, EnvironmentArtifactMetadata, EnvironmentArtifactPayloadRef, EnvironmentArtifactRequirement } from '@objectstack/spec/system';

// Validate data
const result = EnvironmentArtifact.parse(data);
```

---

## EnvironmentArtifact

ObjectStack Environment Artifact envelope (v0)

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **schemaVersion** | `string` | ✅ | Environment artifact envelope schema version |
| **environmentId** | `string` | ✅ | Environment identifier (control-plane scoped) |
| **commitId** | `string` | ✅ | Content-addressable revision id |
| **checksum** | `Object` | ✅ | Artifact integrity checksum |
| **builtAt** | `string` | optional | ISO-8601 timestamp of when the artifact was built |
| **builtWith** | `string` | optional | Build tool identifier |
| **metadata** | `Record<string, any>` | ✅ | Compiled environment metadata grouped by category |
| **functions** | `Object[]` | ✅ | Inlined function code packaged with the artifact |
| **manifest** | `Object` | ✅ | Plugin/driver requirements baked into the artifact |
| **payloadRef** | `Object` | optional | Out-of-band payload reference (reserved for future use) |


---

## EnvironmentArtifactChecksum

Artifact integrity checksum

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **algorithm** | `Enum<'sha256' \| 'sha384' \| 'sha512'>` | ✅ | Hash algorithm used for the artifact checksum |
| **value** | `string` | ✅ | Hex-encoded digest of the artifact body |


---

## EnvironmentArtifactFunction

A single inlined function

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Function machine name (snake_case) |
| **language** | `Enum<'javascript' \| 'typescript'>` | ✅ | Source language of the function code |
| **code** | `string` | ✅ | Inlined function source |
| **source** | `Object` | optional | Source-map metadata for the function |
| **hash** | `string` | optional | Hex SHA-256 of the inlined code |


---

## EnvironmentArtifactFunctionLanguageEnum

Source language of the function code

### Allowed Values

* `javascript`
* `typescript`


---

## EnvironmentArtifactHashAlgorithmEnum

Hash algorithm used for the artifact checksum

### Allowed Values

* `sha256`
* `sha384`
* `sha512`


---

## EnvironmentArtifactManifest

Plugin/driver requirements baked into the artifact

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **plugins** | `Object[]` | optional |  |
| **drivers** | `Object[]` | optional |  |
| **engine** | `Object` | optional |  |


---

## EnvironmentArtifactMetadata

Compiled environment metadata grouped by category

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **objects** | `any[]` | optional |  |
| **fields** | `any[]` | optional |  |
| **views** | `any[]` | optional |  |
| **apps** | `any[]` | optional |  |
| **pages** | `any[]` | optional |  |
| **dashboards** | `any[]` | optional |  |
| **reports** | `any[]` | optional |  |
| **flows** | `any[]` | optional |  |
| **workflows** | `any[]` | optional |  |
| **triggers** | `any[]` | optional |  |
| **agents** | `any[]` | optional |  |
| **tools** | `any[]` | optional |  |
| **skills** | `any[]` | optional |  |
| **permissions** | `any[]` | optional |  |
| **permissionSets** | `any[]` | optional |  |
| **roles** | `any[]` | optional |  |
| **profiles** | `any[]` | optional |  |
| **translations** | `any[]` | optional |  |
| **datasources** | `any[]` | optional |  |
| **datasets** | `any[]` | optional |  |
| **actions** | `any[]` | optional |  |
| **apis** | `any[]` | optional |  |


---

## EnvironmentArtifactPayloadRef

Out-of-band payload reference (reserved for future use)

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **url** | `string` | ✅ | Signed URL pointing at the artifact payload |
| **expiresAt** | `string` | optional | ISO-8601 expiry timestamp |
| **checksum** | `Object` | ✅ | Checksum of the referenced payload |


---

## EnvironmentArtifactRequirement

A plugin or driver dependency declaration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Plugin/driver package id |
| **version** | `string` | optional | SemVer range required by the environment |


---

