SDK Reference

Complete reference for both Maritime SDKs. New here? Start with the Build on Maritime guide.

Language	Package	Install
TypeScript / JS	maritime-sdk	npm install maritime-sdk
Python	maritime	pip install maritime

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
})

Retries are safe by construction: GET/DELETE retry on any transient failure; writes retry only on network errors and 429/503 (never a 5xx that might have applied).

Agents

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

Method	Does
create(params)	Create an agent and start its deploy. Prefer `template`: a bare framework yields a broken image.
provision({externalId, …})	Idempotent get-or-create by `externalId`. The recommended per-customer entry point.
get(id)	Fetch one agent.
list({externalId?, name?})	List agents, optionally filtered.
chat(id, message, opts?)	Send a message, wait for the reply. Auto-wakes a sleeping agent.
start / stop / sleep / restart(id)	Lifecycle transitions.
setEnv(id, key, value, {secret})	Upsert an env var (secrets encrypted at rest).
listEnv(id) / deleteEnv(id, key)	Read / remove env vars.
reloadEnv(id)	Push env changes into the running container.
logs(id, {limit?, level?})	Recent log entries.
delete(id)	Tear down the agent (container + volume + network).

create / provision parameters

Param	Type	Notes
name	string	Unique per account. Required.
template	string	openclaw · zeroclaw · hermes · claude_code · dsh · … (see frameworks)
externalId	string	Your own id for this agent. Filterable; idempotency key for `provision`.
instructions	string	Plain-English persona / system prompt.
env	{key,value,secret}[]	Seed env vars. Secrets encrypted at rest.
idleTtlSeconds	number	Idle seconds before auto-sleep. 0 = always-on.

// 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.

Keys

Mint scoped API keys programmatically. Minting requires the caller's key to carry the manage scope.

Method	Does
create({name, scopes?, expiresInDays?})	Mint a key. The raw key is returned once.
list()	List your keys (raw values never returned again).
revoke(id)	Revoke a key.

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

Webhooks

Receive signed lifecycle events instead of polling. See the webhooks guide for signature verification.

Method	Does
create({url, events?})	Subscribe a URL. Returns the signing `secret` once.
list()	List subscriptions.
test(id)	Deliver a synthetic ping.
delete(id)	Remove a subscription.

Events: agent.deployed · agent.error · agent.sleeping · agent.woken · agent.restarted · agent.stopped.

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.

Method	Does
send({message, kind?, subject?, agentId?, requestId?, statusCode?, tool?, context?})	Send one report. Returns the stored row (202).
list()	The account's last 50 reports, newest first.

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.

Class	When
MaritimeAuthError	401 / 403: bad or under-scoped key
MaritimePaymentRequiredError	402: plan limit reached, or an add-on needs a paid plan
MaritimeNotFoundError	404: no such agent (or not yours)
MaritimeConflictError	409: name already taken
MaritimeRateLimitError	429: rate limited
MaritimeAPIError	any other non-2xx
MaritimeConnectionError	never reached Maritime (network / timeout)

from maritime import MaritimeAPIError

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