title: antpath

antpath

antpath is a TypeScript-first SDK + CLI for running autonomous Claude Managed Agents sessions through the managed antpath service. Everything an agent or human needs is reachable through one import and one binary.

import {
  AntpathClient,        // the only client class — submits durable runs to antpath
  Skill,                // workspace / provider / inline skill bundles
  McpServer,            // MCP server declarations (headers split into secrets server-side)
  ProxyEndpoint,        // per-run managed HTTP proxy endpoint
  AgentsMd,             // AGENTS.md / CLAUDE.md uploads
  File,                 // arbitrary workspace files mounted into the session
  defineRun,            // type-safe wrapper around a credential-free `Blueprint`
  validateProxyAuth     // helper that fails fast on policy/auth mismatch
} from "antpath";

antpath run     --config ./blueprint.json --api-token ant_… \
                --anthropic-api-key sk-ant-… --follow
antpath status  <run-id>             --api-token …
antpath wait    <run-id> [--timeout 8m] [--interval 2s] --api-token …
antpath events  <run-id> [--follow] [--timeout 8m]  --api-token …
antpath outputs <run-id>             --api-token …
antpath download <run-id> [--only outputs|logs|events|metadata] [--out path] --api-token …
antpath cancel  <run-id>             --api-token …
antpath delete  <run-id>             --api-token …
antpath whoami                       --api-token …
antpath skills  <upload|list|get|delete> [flags] --api-token …

The SDK class and the CLI are backed by the same @antpath/shared operations module — any read or write you can do through one, you can do through the other, against the same durable run records. The same npm package also ships the in-container antpath CLI as its bin entry; the worker mounts that CLI inside every run at /mnt/session/uploads/antpath/antpath (Anthropic Managed Agents rebases every session-resource mount under /mnt/session/uploads/, and mounted files have no execute permission so they are invoked through node), so skills can call node /mnt/session/uploads/antpath/antpath proxy … against the per-run manifest. See Agent-first surface design.

The antpath URL defaults to https://api.antpath.ai. Self-hosted deployments override with --antpath-url on the CLI or baseUrl on AntpathClient. The workspace is derived server-side from your API token (1:1 binding), so there is no --workspace flag and no workspaceId option.

Product boundaries

• Multi-provider via the 2026 dual-runtime architecture. The published surface is the same regardless of provider:
  • provider: "anthropic" — defaults to the Anthropic Native runtime (direct /v1/messages from the edge). Opt into the multi-provider runner with runtime: "managed".
  • provider: "deepseek" | "openai" | "gemini" | "mistral" — Goose Managed runtime, per-run Fly Machine spawning the runner-image/ container. BYOK provider-proxy on api.antpath.ai injects the customer's key on the edge (the SDK never sees an upstream key).
  • See references/architecture.md for the full split.
• BYO provider key + MCP credentials + skill references — passed inline on every submission, vaulted for the lifetime of a single run, destroyed at cleanup. Cross-provider keys are rejected loudly at submission time.
• Workspace is the tenant boundary. Workspace identity is derived server-side from the API token (1:1 binding); the SDK / CLI never name it.
• No SDK-side storage of provider keys, MCP credentials, or output file contents.
• Cleanup runs by default; opt into retention with cleanup.session: "retain".

Quickstart (SDK)

import { AntpathClient } from "antpath";

const client = new AntpathClient({
  apiToken: process.env.ANTPATH_API_TOKEN!
  // baseUrl defaults to https://api.antpath.ai — set it for self-hosted deployments.
});

const ref = await client.submitRun({
  model: "claude-haiku-4-5",
  system: "You are a concise automation agent.",
  prompt: "Write a short answer about agent-first SDK design.",
  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
});

const run = await ref.wait();
console.log(run.status);

for (const output of await ref.outputs()) {
  console.log(output.id, output.path);
}

Reusable, credential-free configs use defineRun:

import { defineRun } from "antpath";

const summarise = defineRun((topic: string) => ({
  model: "claude-haiku-4-5",
  system: "You are a concise automation agent.",
  prompt: `Write a short answer about ${topic}.`
}));

const ref = await client.submitRun({
  ...summarise("agent-first SDK design"),
  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
});

Stream events live with ref.stream():

for await (const event of ref.stream()) {
  if (event.type === "agent.message") {
    // typed event helpers live under `antpath`'s event guard exports.
  }
}

The same flow from the CLI (two equivalent forms):

antpath run \
  --api-token "$ANTPATH_API_TOKEN" \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --model claude-haiku-4-5 \
  --system "You are a concise automation agent." \
  --prompt "Write a short answer about agent-first SDK design." \
  --follow

antpath run \
  --api-token "$ANTPATH_API_TOKEN" \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --config ./blueprint.json \
  --follow

--config accepts a JSON file matching the Blueprint shape: { model, system?, prompt, skills?, mcpServers?, environment?, cleanup?, proxyEndpoints?, metadata? }. There is no template wrapper and no {{var}} DSL — interpolate at the call site.

Test commands

pnpm test                # unit (deterministic; uses fakes/snapshots)
pnpm test:e2e            # full top-to-bottom against a real antpath stack + Anthropic
pnpm test:user           # exercises the published package via npm install (offline + live)

pnpm test:user requires ANTPATH_USER_TEST_TARBALL/ANTPATH_USER_TEST_VERSION (+ live target vars for the live siblings). Missing required env is a hard error — there is no silent skip.

Guides

• Quickstart
• Blueprints
• Credentials
• MCP
• Skills
• Outputs
• Events
• Cleanup
• Testing
• Release