SDK Reference

Complete reference for both Maritime SDKs. New here? Start with the Build on Maritime guide. Methods are shown with their TypeScript names; Python uses the same names in snake_case (setEnv is set_env) with keyword arguments.

Both are zero-dependency. Source: github.com/maritime-sh/maritime-sdk.

1. provision({ externalId }) Creates the customer's agent once
2. chat(id, message) Wakes it if it is asleep and sends the message
3. reply Comes back to your code

Your code provisions an agent for a customer, sends it a message, and gets the reply. A sleeping agent wakes on the message.

Client

The API key defaults to MARITIME_API_KEY; the base URL to MARITIME_API_URL or api.maritime.sh.

TypeScript / Python

import { Maritime } from 'maritime-sdk'

const maritime = new Maritime({
  apiKey: 'mk_...',                     // or MARITIME_API_KEY
  baseUrl: 'https://api.maritime.sh',   // or MARITIME_API_URL
  timeout: 60_000,                      // per-request ms
  maxRetries: 2,                        // network + 5xx/429
})

A failed request is retried up to maxRetries times (default 2), waiting 0.5 s, then 1 s, doubling up to 8 s, or the server's Retry-After up to 20 s. GET and DELETE, the lifecycle calls (start, stop, sleep, restart, reloadEnv) and chat, which sends an Idempotency-Key, retry on 429, 500, 502, 503, 504, timeouts and network errors. Other writes retry only on 429 and 503, and when the connection was refused or DNS failed, so nothing was sent; a timeout or another 5xx may already have applied the write, so it is thrown.

Agents

Access via maritime.agents (TS) / client.agents (Python).

Files, skills and share links of an agent hang off maritime.agents:

create / provision parameters

TypeScript / Python

const agent = await maritime.agents.provision({
  externalId: `customer_${userId}`,
  name: `assistant-${userId}`,
  template: 'openclaw',
})

const { response } = await maritime.agents.chat(agent.id, 'Hello')
await maritime.agents.setEnv(agent.id, 'STRIPE_KEY', 'sk_live_...', { secret: true })
const { root } = await maritime.agents.files.list(agent.id)   // browse / upload / download
await maritime.agents.exec(agent.id, ['ls', '-la', root])     // one-shot shell command
await maritime.agents.sleep(agent.id)
await maritime.agents.delete(agent.id)

Exec waits by default. See command execution for detached Python submission, REST retrieval and cancellation, and timeout defaults.

Sandboxes

Linux machines you create, run commands in, pause, snapshot and end from code. They need a key with the sandboxes scope (or manage). Access via maritime.sandboxes, maritime.ephemeral, maritime.snapshots, maritime.secrets, maritime.usage and maritime.sandboxWebhooks (Python: client.sandbox_webhooks and so on). Sandbox calls throw MaritimeSandboxError with a machine-readable code and hint. See Sandboxes and sandbox events.

End users

Your own users, keyed by the id you already hold. Access via maritime.endUsers (TS) / client.end_users (Python). See the end users guide.

Projects

The HTTP front door: route each of your users' messages to their own agent. Access via maritime.projects.

Swarms

Run one command on many sandboxes and collect the results. Access via maritime.swarms (TS) / client.swarms (Python). See Swarms.

Keys

Mint scoped API keys programmatically. Minting requires the caller's key to carry the manage scope. Scopes are provision, deploy, secrets, manage, computers and sandboxes. The default is the first four; manage grants every scope, so a default key also reaches Computers and Sandboxes. A key that should reach only Computers asks for ['computers'], and one for only Sandboxes asks for ['sandboxes'].

TypeScript / Python

const worker = await maritime.keys.create({ name: 'chat-worker', scopes: ['deploy'] }) // worker.rawKey is shown once. Store it now.
const tenant = await maritime.keys.create({ name: 'tenant-a', projectId: agent.projectId })

Webhooks

Receive signed events instead of polling. The webhooks guide lists every event and covers retries and verification.

Verify a delivery with verifyWebhookSignature({secret, body, signature}) (TS, returns a Promise of boolean) or verify_webhook_signature(secret, body, signature) (Python), both exported at the package top level. Pass the raw body and the X-Maritime-Signature header.

Billing, account and network

Feedback

Tell Maritime when a doc is wrong, an example does not run, or a call fails in a way you cannot explain. Built for coding agents. See the feedback guide.

TypeScript / Python

await maritime.feedback.send({
  kind: 'sdk',
  subject: 'agents.chat',
  message: 'chat returned 500 on a fresh agent; docs say sleeping agents auto-wake.',
  requestId: err.requestId,
  statusCode: err.status,
  tool: 'claude-code/2.1.0',
})

Errors

Every failure is a subclass of MaritimeError. API errors expose .status and .detail.

from maritime import MaritimeAPIError

try:
    client.agents.get("nope")
except MaritimeAPIError as err:
    print(err.status, err.detail, err.request_id)

More resources

• Computers: maritime.computers, desktops your own model drives
• Networks: internet policy, exits and private access
• Limits: plan caps, size ceilings and error codes
• Web apps: public agent URLs, visibility and share links