#Deployments

A deployment is a reusable Managed Agents run definition. It stores the agent snapshot, environment, initial user input, resources, vault ids, and optional schedule used to create sessions later.

Official reference: Claude Managed Agents scheduled deployments.

Create A Scheduled Deployment#

Use a scheduled deployment for recurring work such as daily digests, nightly repository checks, weekly compliance scans, or periodic sync jobs.

typescript
const deployment = await client.beta.deployments.create({
    agent: agent.id,
    environment_id: environment.id,
    name: "daily-digest",
    description: "Create the weekday engineering digest.",
    initial_events: [{
        type: "user.message",
        content: [{
            type: "text",
            text: "Summarize yesterday's changes and open risks.",
        }],
    }],
    resources: [{
        type: "github_repository",
        url: "https://github.com/acme/app",
        checkout: { type: "branch", name: "main" },
    }],
    schedule: {
        type: "cron",
        expression: "0 9 * * 1-5",
        timezone: "UTC",
    },
    vault_ids: [llmVault.id],
    metadata: {
        workflow: "daily-digest",
    },
});

When the cron fires, Sandbox0 creates a new session from the stored deployment definition and sends the configured initial events. The created session then follows the normal session lifecycle and event stream.

initial_events is required. Use user.message for normal recurring tasks. system.message can accompany a user event when your SDK version exposes it. Outcome initial events are not supported because Sandbox0 does not implement Managed Agents outcomes.

Schedule Support#

Sandbox0 supports cron schedules with minute-level precision.

Cron seconds, year fields, shortcuts such as @daily, and extended Quartz syntax such as ?, L, W, and # are not accepted.

Pausing a deployment stops future scheduled runs but does not stop sessions already created by the deployment. Unpausing resumes future schedule evaluation; missed triggers are not backfilled.

Run Manually#

Manual runs use the same deployment definition but do not require a schedule.

typescript
const run = await client.beta.deployments.run(deployment.id);

if (run.session_id) {
    console.log(`started session ${run.session_id}`);
}

Use manual runs for ad-hoc retries, operator-triggered workflows, or deployments that should be callable by a product action instead of a cron trigger.

Deployment Runs#

Deployment runs are the audit records for session creation attempts.

typescript
for await (const run of client.beta.deploymentRuns.list({
    deployment_id: deployment.id,
    trigger_type: "schedule",
    limit: 20,
})) {
    console.log(run.id, run.session_id, run.error);
}

A deployment run records whether a session was started. It does not replace the session event stream. After a run has a session_id, use session APIs to read events, stream output, interrupt work, or delete the session.

Lifecycle#

Scheduled session creation failures are recorded on the deployment run. Non-rate-limit failures pause the deployment so operators can inspect and fix the definition before it keeps firing.

Resources And Secrets#

Deployments can include the same resources used by sessions. File resources and GitHub repository resources are materialized into each created session workspace.

Repository authorization tokens are accepted when creating or updating a deployment, but they are never returned by read APIs. Sandbox0 stores resource secret material encrypted at rest and resolves it only when creating a session from the deployment.

Sandbox0 Notes#

• A deployment snapshots the agent version used at creation time, just like a session.
• Sessions created by deployments use the same Sandbox0 persistent workspace, network policy, credential projection, and harness selection as sessions created directly.
• Attach exactly one LLM vault for normal deployments.
• Prefer deployment runs for operational audit and session events for agent output.

Next Steps#