Quickstart

From nothing to a live, per-customer agent in five minutes. Everything runs on your backend. Your API key never touches a browser.

1. Install

TypeScript
Python

npm install maritime-sdk

Zero dependencies. TypeScript needs Node 18+ (or Bun / Deno / edge); Python needs 3.9+.

2. Get an API key

Mint a key from the dashboard ( Settings → API keys) or with maritime keys create. A default key is full-access; use Advanced to scope it down (see Authentication).

Settings → API keys. Store the key as MARITIME_API_KEY in your backend.

A new account starts its 7-day free trial (card first, not charged then) before its first machine; until then a create fails with 402trial_required and a checkout link. Start it from the dashboard or with maritime billing checkout.

Both SDKs read MARITIME_API_KEY from the environment automatically, or you can pass it explicitly: new Maritime({ apiKey }) / Maritime(api_key=...).

3. Provision an agent per customer

Tag each agent with your own id via externalId. provision is idempotent on it: it returns the existing agent if there is one, else creates a new one. Safe to call on every sign-in.

TypeScript
Python

// when your user signs up
import { Maritime } from 'maritime-sdk'

const maritime = new Maritime({ apiKey: process.env.MARITIME_API_KEY })

const agent = await maritime.agents.provision({
  externalId: `customer_${user.id}`,   // your id for this agent
  name: `assistant-${user.id}`,
  template: 'openclaw',
  instructions: 'You are a helpful assistant for ' + user.name + '.',
})

That agent is now live on Maritime's infrastructure, and it shows up in your dashboard like any other, so you can watch, debug, or take over any customer's agent:

Every agent you provision is a real, inspectable micro-VM in your dashboard.

4. Talk to it

A freshly-provisioned agent boots in the background; a returning user's agent is already warm. Sleeping agents wake automatically, and the call waits for the reply.

TypeScript
Python

const { response } = await maritime.agents.chat(agent.id, 'What can you do?')

// continue a thread:
await maritime.agents.chat(agent.id, 'And after that?', { conversationId: 'thread-1' })

Put it together

A single request handler that gives a user their agent and relays a message:

Next.js
FastAPI

import { Maritime } from 'maritime-sdk'

const maritime = new Maritime({ apiKey: process.env.MARITIME_API_KEY })

export async function POST(req: Request) {
  const { userId, message } = await req.json()

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

const { response } = await maritime.agents.chat(agent.id, message)
  return Response.json({ reply: response })
}

Agents → Provision, chat, configure, lifecycle
Webhooks → Get notified on lifecycle events
Examples → Runnable files on GitHub