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.

Client

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

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

// Idempotent per-customer provisioning (recommended)
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.

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 ephemeral 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 and computers. The default is the first four, which reach Computers through manage; a key that should reach only Computers asks for ['computers']. A key created with projectId works only on that project's front door and usage routes and is refused everywhere else.

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.

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