Deployments

A deployment is a dedicated AI agent for one customer, running in an isolated container with a persistent filesystem. Bring your system prompt, skills, MCP tools, and connector secrets — the deployment ships with session management, observational memory, automations, self-learning, and an SSE endpoint to stream agent events. All examples use the Herm SDK:

import Herm from "herm";

const herm = new Herm(); // reads PRISM_API_KEY

Create a deployment

POST /v1/deployments

Provisioning usually completes in seconds. Poll Get a deployment until status is ready, then start sending messages.

const deployment = await herm.deployments.create({
  customer_id: "cus_123",
  name: "Acme Creative Agent",
  runtime: "hermes",
  model: "anthropic/claude-sonnet-4.5",
  system_prompt:
    "You are Acme's media generation agent. Help the user plan, create, and iterate on high-performing short-form videos.",
  sandbox: {
    enabled: true,
    type: "docker",
    persistent_filesystem: true,
  },
  mcp_servers: [
    {
      name: "prism-media",
      url: "https://api.prismvideos.com/mcp",
      tools: ["search_models", "generate_image", "generate_video"],
    },
  ],
  skills: [
    {
      name: "ugc-video-creation",
      source: "file",
      path: ".prism/skills/ugc-video-creation/SKILL.md",
    },
    {
      name: "storyboarding",
      source: "inline",
      content:
        "---\nname: storyboarding\ndescription: Create shot-by-shot storyboards for short-form videos\n---\n# Storyboarding\n...",
    },
    {
      name: "social-media-visual-effects",
      source: "url",
      url: "https://example.com/skills/social-media-visual-effects/SKILL.md",
    },
  ],
  secrets: {
    META_ADS_TOKEN: "sec_meta_ads_token",
    GOOGLE_DRIVE_TOKEN: "sec_google_drive_token",
  },
  features: {
    memory: true,
    dreaming: true,
    automations: true,
    steering: true,
    filesystem_webhooks: true,
  },
});

Parameters

Parameter	Type	Required	Description
`customer_id`	string	Yes	Your identifier for the customer this agent serves. One agent per customer is the recommended model
`name`	string	Yes	Human-readable deployment name
`runtime`	string	No	Agent harness to run. Currently `hermes` (default)
`model`	string	No	Model in `provider/model` form, such as `anthropic/claude-sonnet-4.5`. No provider lock-in
`system_prompt`	string	Yes	The agent’s system prompt
`sandbox`	object	No	Sandbox configuration — see Sandbox
`mcp_servers`	array	No	Your MCP servers exposing first-party tools — see MCP servers
`skills`	array	No	Skill files that teach the agent your domain playbooks — see Skills
`secrets`	object	No	Map of environment variable names to secret references (`sec_...`) for connectors
`features`	object	No	Feature flags — see Features

Sandbox

Field	Type	Default	Description
`enabled`	boolean	`true`	Run the agent in an isolated container
`type`	string	`docker`	Sandbox backend
`persistent_filesystem`	boolean	`true`	Persist the agent’s workspace across sessions

MCP servers

Field	Type	Required	Description
`name`	string	Yes	Unique server name
`url`	string	Yes	URL of your MCP server
`tools`	string[]	No	Allowlist of tool names. Omit to expose all tools

Skills

Each skill is loaded from one of three sources:

`source`	Required fields	Description
`file`	`name`, `path`	A `SKILL.md` file uploaded to the deployment
`inline`	`name`, `content`	Skill markdown provided directly in the request
`url`	`name`, `url`	A `SKILL.md` fetched from a public URL

Features

Field	Type	Default	Description
`memory`	boolean	`true`	Observational memory across sessions
`dreaming`	boolean	`false`	Idle-time self-learning between sessions
`automations`	boolean	`true`	Scheduled and recurring agent runs
`steering`	boolean	`true`	Human-in-the-loop approvals mid-run
`filesystem_webhooks`	boolean	`false`	Webhook notifications on agent filesystem changes

Response

{
  "deployment_id": "dep_7xK9s2",
  "customer_id": "cus_123",
  "runtime": "hermes",
  "status": "ready",
  "model": "anthropic/claude-sonnet-4.5",
  "thread_id": "thr_default_8a1",
  "filesystem": {
    "workspace_path": "/workspace",
    "persistent": true
  },
  "events": {
    "transport": "sse",
    "url": "https://api.prismagents.com/v1/deployments/dep_7xK9s2/events"
  }
}

Response fields

Field	Type	Description
`deployment_id`	string	Deployment ID to pass to other endpoints
`customer_id`	string	The customer identifier you supplied
`runtime`	string	Agent harness running in the deployment
`status`	string	One of `provisioning`, `ready`, `error`
`model`	string	Resolved model identifier
`thread_id`	string	Default thread for Send Message
`filesystem.workspace_path`	string	Path of the agent’s workspace inside the container
`filesystem.persistent`	boolean	Whether the workspace persists across sessions
`events.transport`	string	Always `sse`
`events.url`	string	Stream Events endpoint for this deployment

Get a deployment

GET /v1/deployments/:deployment_id

Returns the current state of a deployment, including created_at.

const deployment = await herm.deployments.get("dep_7xK9s2");

console.log(deployment.status); // "ready"

{
  "deployment_id": "dep_7xK9s2",
  "customer_id": "cus_123",
  "name": "Acme Creative Agent",
  "runtime": "hermes",
  "status": "ready",
  "model": "anthropic/claude-sonnet-4.5",
  "thread_id": "thr_default_8a1",
  "filesystem": {
    "workspace_path": "/workspace",
    "persistent": true
  },
  "events": {
    "transport": "sse",
    "url": "https://api.prismagents.com/v1/deployments/dep_7xK9s2/events"
  },
  "created_at": "2026-06-11T18:21:09Z"
}

List deployments

GET /v1/deployments

Returns the deployments owned by your API key, newest first.

const { data, next_cursor } = await herm.deployments.list({
  customer_id: "cus_123",
  limit: 20,
});

Parameters

Parameter	Type	Required	Description
`customer_id`	string	No	Filter to a single customer’s deployments
`status`	string	No	Filter by status: `provisioning`, `ready`, or `error`
`limit`	integer	No	Page size, from 1 to 100. Defaults to 20
`cursor`	string	No	Pagination cursor from a previous response

{
  "data": [
    {
      "deployment_id": "dep_7xK9s2",
      "customer_id": "cus_123",
      "name": "Acme Creative Agent",
      "runtime": "hermes",
      "status": "ready",
      "model": "anthropic/claude-sonnet-4.5",
      "created_at": "2026-06-11T18:21:09Z"
    }
  ],
  "next_cursor": null
}

Update a deployment

PATCH /v1/deployments/:deployment_id

Updates a live deployment’s configuration. Changes apply to the agent’s next run; memory, files, and conversation history are untouched.

const updated = await herm.deployments.update("dep_7xK9s2", {
  name: "Acme Creative Agent v2",
  model: "anthropic/claude-opus-4-8",
  system_prompt:
    "You are Acme's media generation agent. Always propose three creative directions before generating.",
  // Arrays are fully replaced
  skills: [
    {
      name: "storyboarding",
      source: "url",
      url: "https://acme.com/skills/storyboarding/SKILL.md",
    },
  ],
  // Maps are merged at the key level
  secrets: {
    RESEND_TOKEN: "sec_acme_resend",
  },
  features: {
    dreaming: true,
  },
});

Update semantics

Field type	Behavior
Scalars (`name`, `model`, `system_prompt`)	Replaced with the new value
Arrays (`mcp_servers`, `skills`)	Fully replaced. Pass `[]` to clear
Maps (`secrets`, `features`)	Merged at the key level. Set a key to `null` to remove it
Omitted fields	Preserved
`customer_id`, `runtime`	Immutable — create a new deployment instead

If the update produces no change, the existing deployment is returned unchanged. To modify skills and MCP servers incrementally instead of replacing the arrays, use the Skills and Tools APIs.

Delete a deployment

DELETE /v1/deployments/:deployment_id

Stops the agent, tears down its container, and deletes the deployment.

Deletion is permanent. The agent’s workspace, memory, skills, and automations are destroyed unless you pass retain_filesystem: true.

await herm.deployments.delete("dep_7xK9s2", { retain_filesystem: true });

Parameters

Parameter	Type	Required	Description
`retain_filesystem`	boolean	No	Keep a snapshot of the workspace for 30 days. Defaults to `false`

{
  "deployment_id": "dep_7xK9s2",
  "status": "deleted"
}

Errors

Status	Error	When
400	`validation_error`	Invalid request body or query parameters
401	`unauthorized`	Missing or invalid API key
402	`insufficient_credits`	The account does not have enough credits
403	`forbidden`	API key lacks the required scope
404	`not_found`	Deployment does not exist
422	`invalid_skill`	A skill could not be fetched or parsed
422	`invalid_secret_ref`	A secret reference does not exist

See Errors for the full error reference.

​Create a deployment

​Parameters

​Sandbox

​MCP servers

​Skills

​Features

​Response

​Response fields

​Get a deployment

​List deployments

​Parameters

​Update a deployment

​Update semantics

​Delete a deployment

​Parameters

​Errors

Create a deployment

Parameters

Sandbox

MCP servers

Skills

Features

Response

Response fields

Get a deployment

List deployments

Parameters

Update a deployment

Update semantics

Delete a deployment

Parameters

Errors