# Maritime, full documentation for AI agents

> Index: https://maritime.sh/llms.txt. Setup procedure: https://maritime.sh/agents.md.
> Each section below is also served on its own at the "Source" URL, and every docs page is served as markdown when .md is appended to its URL.

---

## Setup procedure for AI agents
Source: https://maritime.sh/agents.md

# Maritime: setup procedure for AI agents

> You are an AI agent reading https://maritime.sh/agents.md. This is a procedure.
> Execute the steps in order. It is idempotent: a step that is already done
> is skipped, not repeated. Do not merely explain the steps to the user.

Maritime hosts AI agents. Each agent gets its own persistent micro-VM: a real
Firecracker VM with a disk at /data that survives sleep, restart, and
redeploy. Agents sleep when idle (free while asleep) and wake in about a
second. Hosting is a flat plan, nothing is metered. The free plan includes 3
machines, no card.

Ask the user a question only when their input is genuinely required: their
email and password for a new account, which agent to deploy when there are
several, and approving a device login or clicking a verification link in
their inbox.

## Step 1: identify yourself and your environment

Note which of these you are, it changes step 3:

- Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode, Aider: you run in the
  user's terminal, usually with no browser you can open. Prefer the device
  login.
- An agent inside a sandbox with no outbound browser at all: same as above.
- A desktop app with a browser: the browser login also works.

Check the environment:

```bash
node --version                 # need 20.12 or later
maritime --version             # absent, or older than 1.9.0, means install below
```

## Step 2: install the CLI

```bash
npm install -g maritime-cli    # the command is `maritime`
maritime --version
```

If a flag in this procedure is unknown to the installed CLI, run
`npm install -g maritime-cli@latest` and retry once.

## Step 3: authenticate

Try these in order and stop at the first that works.

1. Already signed in: `maritime whoami --json` exits 0. Continue to step 4.
2. `MARITIME_TOKEN` is set in the environment: the CLI reads it first. Run
   `maritime whoami --json`; exit 2 means the token is wrong.
3. The user has an account and you have no browser:
   `maritime login --device --json`. The CLI prints one JSON line on stderr
   with `user_code` and `verification_uri_complete`. Show both to the user,
   ask them to open the URL and approve, and wait. The command returns when
   they approve (it expires after 15 minutes).
4. The user has an account and a browser on this machine: `maritime login`.
5. The user has no account and is present: ask for an email and a password,
   then `maritime signup -e <email> -p <password> -n <name> --json`. Never
   invent an email. Signup saves a login token and returns
   `emailVerified: false`.
6. The user has no account and you should not stop to ask: deploy first and
   let them claim it later. Skip to step 6 and add `--claim-later` to the
   create command. It needs no login: the agent runs under a temporary
   account for 72 hours with a claim link, the CLI stays signed in with a
   temporary key, and one agent is the limit. A template agent must bring
   its own model key (`-e ANTHROPIC_API_KEY=...` or `-e OPENAI_API_KEY=...`)
   because the temporary account has no LLM credit. Put the claim link in
   your final report; the user opens it, signs in or signs up, and the agent
   moves into their account.

Do not print the password back. Do not paste tokens into chat.

## Step 4: the email verification wall

Until the user clicks the link Maritime emailed them, these are refused with
status 403 and `error.code` `email_not_verified`: create, deploy, start,
restart, keys create, computer creation. Listing, status, logs, and templates
work before verification.

When you see `email_not_verified`: tell the user to open their inbox and
click the link, offer `maritime login --resend` if it did not arrive, wait
for them to say it is done, then retry the same command. Do not create a
second account.

## Step 5: learn the contract

```bash
maritime guide --json          # every command and flag, from the installed CLI
```

Rules that apply to every command: pass `--json`; success is one JSON value
on stdout; failure is `{"ok": false, "error": {"code", "message", "status"}}`
on stderr; exit codes are 0 ok, 1 error, 2 auth, 3 not found, 4 usage. Never
guess flags. Full contract: https://maritime.sh/docs/cli/llms.txt

## Step 6: deploy

Choose exactly one recipe.

A. The user wants a ready-made agent (no code of their own):

```bash
maritime templates --json                                   # ids: openclaw, hermes, zeroclaw, claude_code, codex, dsh
maritime create <name> --template openclaw --json
```

B. The user has a repo with a Dockerfile at its root (any framework):

```bash
maritime create <name> --repo <git url> --json              # builds on Maritime, 1 to 3 minutes
```

The container must listen on 0.0.0.0:$PORT (injected, never hardcode 8080),
answer GET /health with any 2xx, answer POST /chat with JSON
{"message": "..."} within 30 seconds, and keep state under /data. If the repo
does not meet this, add the smallest server that does before deploying.
Contract and examples: https://maritime.sh/docs/frameworks/custom.md

C. The user wants a public web app on its own HTTPS URL:

```bash
maritime create <name> --repo <git url> --public --port <port> --json
```

D. The user's product should give every end user their own agent: stop, and
point them at the SDK instead of deploying by hand: https://maritime.sh/docs/build.md

Secrets the agent needs go in after create, never into the repo:

```bash
maritime env set <name> KEY=value --reload --json
```

Scheduled work: timers inside a sleeping VM do not fire. Use
`maritime triggers create <name> --type cron --cron "<expr>" --json`.

## Step 7: verify

```bash
maritime status <name> --json                               # poll until .status is "active"
maritime chat <name> "hello" --json | jq -r '.response'     # templates and chat-capable containers
maritime logs <name> --json                                 # custom containers: the server is listening
```

A build failure shows in `maritime history <name> --json` (buildLog). Fix
the Dockerfile and run `maritime deploy <name> --json`. Do not create a
second agent to work around a failed build.

## Step 8: leave the repo ready for next time

If you deployed from a repo and `.claude/skills/maritime/SKILL.md` does not
exist, run `maritime init --no-create` there (it writes the skill and a
maritime.json), or fetch https://maritime.sh/SKILL.md into that path. The next agent
session in that repo then knows Maritime without reading this page.

## Step 9: report

End with exactly this shape, filled in with what actually happened:

- Status: deployed and verified | deployed, not verified | blocked (why)
- Agent: <name>, <template or repo>, dashboard https://maritime.sh/agents
- Claim link, if you used --claim-later: the URL and the expiry time
- Auth: which path from step 3 was used; whether verification is pending
- Changes made: files added or edited in the repo, env vars set (names only)
- Verification: the status value and the chat reply or log line you saw
- Next action for the user: one line, or "none"

Do not finish with a list of steps that were not attempted. Execute the
procedure first, then report the actual result.

## Known behaviours

- `maritime login` (no flags) opens a browser and waits up to 120 seconds
  for a localhost callback. In a sandbox this hangs; use `--device`.
- `create` and `delete` never prompt. A missing name exits 4; `delete`
  needs `--yes`.
- Flag-parse errors (unknown option) exit 1 with plain text on stderr even
  under `--json`. Treat that as a usage bug, not an API failure.
- `error.code` `agent_unavailable` on chat: the agent is not running. Run
  `maritime start <name>`, wait a few seconds, retry.
- `error.code` `seat_limit` (status 402): the plan is full. Show
  `error.message` to the user unchanged; it names the fix.
- Most templates need no model key (Maritime's metered LLM proxy).
  `claude_code` needs ANTHROPIC_API_KEY as a secret env var.
- `--claim-later` needs maritime-cli 1.10.0 or later. The temporary key
  cannot create a second agent (`seat_limit`) and expires with the claim
  link. After the claim, the user mints a normal key.
- Long-running automation should use an API key, not a login token:
  `maritime keys create --name <purpose> --json` (after verification) and
  export `raw_key` as MARITIME_TOKEN. mk_ keys never expire.

## More

- Index of every page: https://maritime.sh/llms.txt
- Every docs page as markdown: append .md to its URL, for example
  https://maritime.sh/docs/quickstart.md
- REST API: https://api.maritime.sh/openapi.json
- The skill file for your skills directory: https://maritime.sh/SKILL.md

---

## Maritime CLI: instructions for AI agents
Source: https://maritime.sh/docs/cli/llms.txt

# Maritime CLI: instructions for AI agents

Copy this file into your agent's context (CLAUDE.md, AGENTS.md, or a system
prompt), or let the agent fetch it from https://maritime.sh/docs/cli/llms.txt.
It teaches an LLM to operate Maritime (https://maritime.sh): a cloud that hosts
AI agents in serverless micro-VMs with persistent storage at /data. Agents
sleep when idle, wake in about a second on the next message or trigger, and
hosting is flat-priced with no usage metering.

The same contract is available offline: `maritime guide` prints a paste-able
version of this file, and `maritime guide --json` emits the full command and
flag manifest, introspected live from the installed CLI, so it can never drift.
Prefer that manifest over guessing flags.

## Setup

1. Install: npm install -g maritime-cli
   (the npm package is maritime-cli; the command is maritime; needs Node 20.12+;
   1.10.0 or later has `login --device`, `signup`, and `create --claim-later`)
2. Authenticate, first path that works wins:
   - MARITIME_TOKEN in the environment (an mk_ key or a login token); the CLI
     reads it before anything else.
   - No browser (a sandbox, SSH, a coding agent): maritime login --device --json
     prints one JSON line on stderr with user_code and verification_uri_complete;
     show both to the user and wait for their approval (15 minute expiry).
   - A browser on this machine: maritime login
   - No account, user present: maritime signup -e <email> -p <password> -n <name> --json
     (ask the user for the email and password; never invent them)
   - No account, do not stop: add --claim-later to maritime create. No login
     needed; the agent runs under a temporary account for 72 hours and the
     response carries a claimUrl the user opens to keep it. One agent only;
     template agents must bring their own model key (-e ANTHROPIC_API_KEY=...).
     Needs maritime-cli 1.10.0 or later.
3. Verify: maritime whoami --json
   (exit code 2 means the token is missing, expired, or wrong)
4. The email verification wall: until the user clicks the link Maritime
   emailed them, create, deploy, start, restart, keys create, and computer
   creation are refused with status 403 and error.code "email_not_verified".
   Ask the user to click the link (maritime login --resend sends it again),
   then retry the same command. List, status, logs, and templates work
   before verification.
5. Long-running automation: once verified, mint a key that never expires:
   maritime keys create --name my-agent --json (raw_key is shown once), and
   export MARITIME_TOKEN=mk_...

Full setup procedure, step by step: https://maritime.sh/agents.md

MARITIME_API_URL overrides the API base (default https://api.maritime.sh).

## The contract

- Pass --json on EVERY command.
  Success: one JSON value on stdout, stderr empty.
  Failure: {"ok": false, "error": {"code": "...", "message": "...", "status": 401}} on stderr, stdout empty.
  Read stdout for results, branch on the exit code, never scrape human text.
- Exit codes: 0 success, 1 generic error (request/server/network), 2 auth,
  3 not found (no such agent), 4 usage (missing or invalid arguments).
  Caveat: flag-parse errors (unknown option, missing required argument) exit 1
  with PLAIN TEXT on stderr even with --json; only CLI-validated errors use
  exit 4 and the JSON error shape. Treat unparseable stderr as a usage bug.
- Anywhere a command takes <agent>, pass the exact agent name or an ID prefix.
  Inside a directory linked with maritime init/link, the agent argument can be
  omitted; the CLI resolves the linked agent.

## Core tasks

# Discover templates, create an agent, wait for it, talk to it:
maritime templates --json
maritime create my-agent --template openclaw --json
maritime status my-agent --json          # wait for "active"
maritime chat my-agent "introduce yourself" --json | jq -r '.response'

# No account yet and nobody to ask: deploy now, claim later (72 h, 1 agent):
maritime create my-bot --repo https://github.com/you/agent --claim-later --json

# Deploy your own code (any framework; Dockerfile at the repo root):
maritime create my-bot --json
maritime deploy my-bot --source github --repo https://github.com/you/agent --branch main --wait --json

# Serve a repo on a public no-login URL (sleeps idle, wakes on the next visit):
maritime create my-app --repo https://github.com/you/app --public --port 3000 --json

# Encrypted env vars (secret by default; --reload pushes into the running agent):
maritime env set my-agent OPENAI_API_KEY=sk-... --reload --json
maritime env import my-agent ./prod.env --reload --json
maritime env list my-agent --json

# Inspect and debug:
maritime list --json
maritime logs my-agent --level error --json
maritime info my-agent --json
maritime history my-agent --json         # build/deploy attempts + buildLog
maritime exec my-agent ls /data --json | jq -r '.stdout'

# Message an agent AS one of your end users (sticky per-user routing through
# the project front door; same --user always reaches the same instance):
maritime message my-agent --user cust_42 "where is my order?" --json | jq -r '.reply'

# Lifecycle (rarely needed; agents sleep and wake on their own):
maritime start my-agent --json
maritime sleep my-agent --json
maritime restart my-agent --json         # also picks up new env vars
maritime delete my-agent --yes --json    # --yes is REQUIRED non-interactively

## Scheduling

Timers inside a sleeping agent do not fire. Put scheduled work on platform
triggers: maritime triggers list <agent>, and
maritime triggers create <agent> --type cron --cron "0 9 * * *".
A cron trigger wakes the agent; set config.prompt via the API to also deliver
a message on each fire. A custom container can instead serve GET /schedules
and Maritime registers the wakes for it.
Details: https://maritime.sh/docs/triggers

## Gotchas

- create and delete never prompt: a missing name or a missing --yes exits with
  code 4 instead of hanging.
- Env changes apply on the next boot unless you pass --reload (or run
  maritime env reload <agent>).
- If chat fails with error.code "agent_unavailable", the agent is not running:
  maritime start <agent>, wait a few seconds, retry.
- A 404 or "not running" on file/exec operations usually means the agent is
  asleep or errored: start it and retry; do not recreate it.
- mk_ keys never expire; browser-login tokens do. Use mk_ for automation.
- LLM access: most templates work with no model key (Maritime's metered LLM
  proxy). The claude_code template is the exception: it always needs your own
  ANTHROPIC_API_KEY as a secret env var.

## More

- Human-readable CLI reference: https://maritime.sh/docs/cli
- Drive-Maritime-from-an-AI-agent guide: https://maritime.sh/docs/ai-agents
- REST API: https://maritime.sh/docs/api
- Building a product where every customer gets an agent? Use the SDK from your
  backend instead: https://maritime.sh/docs/build

---

## Maritime docs
Source: https://maritime.sh/docs/.md

# Maritime docs

Maritime is the cloud built for AI agents: serverless containers with memory, triggers, and
channels that sleep when idle and wake on the next message. Everything here is drivable from the
dashboard, the [CLI](https://maritime.sh/docs/cli), the [API](https://maritime.sh/docs/api), or
the [SDK](https://maritime.sh/docs/build). Start with whichever door matches what you came to do.

- [Run a ready-made agent](https://maritime.sh/docs/quickstart): Deploy a complete agent from a
  template and talk to it, in under 5 minutes. No code.
- [Build a platform with the SDK](https://maritime.sh/docs/build): Give every one of your users
  their own agent with the TypeScript or Python SDK.
- [Ship your own code](https://maritime.sh/docs/frameworks/custom): Any Docker container becomes
  an agent: three endpoints get you sleep/wake, channels, and triggers.
- [How Maritime works](https://maritime.sh/docs/how-it-works): The mental model in 5 minutes:
  agents, memory, sleep/wake, triggers, and what it costs.

## Popular pages

- [Choose a framework](https://maritime.sh/docs/frameworks)
- [Public web agents](https://maritime.sh/docs/web-apps)
- [Environment variables & secrets](https://maritime.sh/docs/configuration#environment-variables)
- [Triggers & schedules](https://maritime.sh/docs/triggers)
- [Connect Telegram, WhatsApp, or Google](https://maritime.sh/docs/channels)
- [Migrate from AWS, Heroku, or a VPS](https://maritime.sh/docs/migrations)

## References

- [CLI reference](https://maritime.sh/docs/cli)
- [REST API](https://maritime.sh/docs/api)
- [SDK reference](https://maritime.sh/docs/sdk)
- [Limits & errors](https://maritime.sh/docs/limits)

> **Note: Driving Maritime from an AI agent?**
>
> Paste one prompt into Claude, Cursor, or any assistant and it can install the CLI, authenticate,
> and deploy agents for you. The full machine-readable contract is always available via
> `maritime guide --json`.
>
> Copy button: "Copy prompt for your agent" copies the prompt below.
>
> [The AI-agent guide →](https://maritime.sh/docs/ai-agents)

```
You are operating Maritime (https://maritime.sh) for me: a cloud platform that hosts AI agents. Each agent runs in its own serverless micro-VM with persistent storage at /data; it sleeps when idle, wakes on the next message, and hosting is flat-priced with no usage metering.

SETUP
1. Install the CLI: npm install -g maritime-cli (the package is maritime-cli, the command is maritime).
2. Authenticate: ask me for an API token, then export it as the MARITIME_TOKEN environment variable. I can mint a long-lived key (mk_...) at https://maritime.sh/developers, or grab a token at https://maritime.sh/cli/auth. Never run interactive "maritime login" yourself.
3. Verify: maritime whoami --json (exit code 2 means the token is missing or wrong).

RULES
- Pass --json on every command. Success prints one JSON value to stdout; failure prints {"ok": false, "error": {"code": "...", "message": "..."}} to stderr. Branch on exit codes: 0 success, 1 generic error, 2 auth, 3 not found, 4 usage.
- Run "maritime guide --json" once to discover the full command and flag surface. It is introspected live and authoritative; do not guess flags.
- Anywhere a command takes <agent>, use the exact agent name or an ID prefix.

COMMON TASKS
- List available templates: maritime templates --json
- Create an agent from a template: maritime create my-agent --template openclaw --json
- Deploy my own repo (any framework, needs a Dockerfile): create the agent, then: maritime deploy <agent> --source github --repo <url> --branch main --json
- Talk to an agent: maritime chat <agent> "your message" --json (read .response; sleeping serverless agents wake automatically)
- Set an encrypted secret: maritime env set <agent> KEY=value --reload --json (without --reload it applies on next boot)
- Inspect: maritime list --json, maritime status <agent> --json, maritime logs <agent> --json, maritime info <agent> --json; run a command inside the agent: maritime exec <agent> <cmd> --json
- Lifecycle: maritime start | stop | restart | sleep <agent> --json; deleting requires --yes

GOTCHAS
- mk_ API keys never expire; browser login tokens do. Use an mk_ key for anything long-running.
- If chat returns error code agent_unavailable, the agent is not running: maritime start <agent>, wait a few seconds, retry.
- create and delete never prompt; a missing name or --yes exits with code 4.

Full instructions file: https://maritime.sh/docs/cli/llms.txt

START by checking whether the maritime CLI is installed and MARITIME_TOKEN works, then ask me what I want to deploy.
```

---

## Quickstart
Source: https://maritime.sh/docs/quickstart.md

# Quickstart

Deploy your first agent and talk to it, in under 5 minutes. Everything below also works
from the [dashboard](https://maritime.sh/dashboard) without a terminal; the screenshots show
the equivalent clicks.

*Recording: The whole quickstart, recorded against production: install the CLI, list templates,
create an openclaw agent, check its status, and send it a first chat message.*

## 1. Install the CLI

```
npm install -g maritime-cli
```

Requires Node.js 20.12 or later. Prefer clicking? Skip the CLI entirely and do all of this from
the dashboard.

## 2. Sign in

Log in with your Maritime account (opens your browser), or create one; the free plan includes
3 agents, no card required:

```
maritime login

# No account yet?
maritime signup
```

## 3. Pick a template

Templates are complete, working agents: pick one and it deploys pre-configured. Not sure which?
[Choose a framework](https://maritime.sh/docs/frameworks) compares them; `openclaw` is the
general-purpose default.

```
maritime templates

# Output:
# NAME                FRAMEWORK    DESCRIPTION
# OpenClaw Agent      openclaw     Autonomous AI agent with 100+ skills.
# Hermes Agent        hermes       Self-improving Python agent with memory.
# ZeroClaw Agent      zeroclaw     Ultra-lightweight Rust agent.
# Claude Code         custom       Coding agent with real tools in a persistent workspace.
# DeepSeek Harness    dsh          Plugin-based harness with a full web workbench.
# ...
```

`--template` takes the **template id** (`openclaw`, `hermes`, `zeroclaw`, `claude_code`, `dsh`),
not the framework column; the ids are listed on
[Choose a framework](https://maritime.sh/docs/frameworks).

*Screenshot: The same templates power the dashboard's New agent flow. The CLI and the dashboard
create identical agents.*

## 4. Create the agent

One command creates *and* deploys it; there is no separate deploy step. It flips to `active` in
under a minute:

```
maritime create my-agent --template openclaw

maritime status my-agent   # wait for status: active
```

*Recording: The same create flow in the dashboard: pick the OpenClaw template, name the agent, and
watch the deploy pipeline run until the agent turns Active.*

## 5. Talk to it

This is the whole point. Sleeping agents wake on their own, and the call waits for the reply:

```
maritime chat my-agent "introduce yourself and list three things you can do"
```

No LLM key needed: the OpenClaw template routes through Maritime's LLM proxy by default, billed
against your account's [AI credits](https://maritime.sh/docs/billing#ai-credits) (new accounts
start with a small seed). The same chat works from the agent's page in the dashboard.

## 6. Add keys & config (optional)

Bring your own model key to pay your provider directly instead of using AI credits, or add any
other credentials your agent needs. Variables are secret by default: encrypted at rest, masked in
the UI.

```
maritime env set my-agent OPENAI_API_KEY=sk-... --reload
```

One exception to know: the [Claude Code](https://maritime.sh/docs/frameworks/claude-code) template
always needs your own `ANTHROPIC_API_KEY` (the proxy speaks the OpenAI format, which Claude Code
does not use). Details in [Env vars & sizing](https://maritime.sh/docs/configuration).

*Screenshot: Env vars live in the agent's Settings tab. Variables are marked secret by default:
stored encrypted, always masked in the UI. Uncheck Secret for plain-text config values.*

## 7. See what it's doing

```
maritime logs my-agent
```

*Screenshot: The same log stream lives on the agent's Overview tab; the Console tab has the
interactive terminal and the agent's files.*

## Shipping a web app instead?

Any repo with a Dockerfile can be served on a public, no-login URL that sleeps when idle and wakes
on the next visit:

```
maritime create my-app --repo https://github.com/you/app --public --port 3000
```

See [Public web agents](https://maritime.sh/docs/web-apps) for the full picture, or
[Deploy any container](https://maritime.sh/docs/frameworks/custom) to make your own code a
chattable agent.

> **Note: What happens next?**
>
> Your agent auto-sleeps when idle and wakes on the next message, trigger, or webhook; you never
> manage that. It counts against your plan's included agents from the moment it exists, and how
> much it runs never changes the bill. Park it deliberately with `maritime sleep my-agent`
> whenever you like.
>
> - [Understand the platform in 5 minutes](https://maritime.sh/docs/how-it-works)
> - [Connect Telegram, WhatsApp, or Google](https://maritime.sh/docs/channels)
> - [Put it on a schedule](https://maritime.sh/docs/triggers)
> - [Understand what it costs](https://maritime.sh/docs/billing)

---

## How Maritime works
Source: https://maritime.sh/docs/how-it-works.md

# How Maritime works

The mental model behind every other page in these docs, on one page. Five minutes here saves an
hour of guessing later.

## The shape of an agent

An agent is a long-lived program running in its own isolated VM (a sandboxed container) with four
things attached:

- **A persistent volume**, mounted at `/data` for most templates. This is the agent's memory: it
  survives restarts, redeploys, and sleep/wake. Everything outside it is disposable.
- **Encrypted environment variables**: API keys and config, stored encrypted at rest and injected
  only into that agent's VM. See [Env vars & sizing](https://maritime.sh/docs/configuration).
- **A chat front door**. The dashboard chat, the CLI, the REST API, and channels like Telegram all
  deliver messages down the same path and wait for the agent's reply.
- **A framework**: the program that actually thinks. Pick a ready-made one
  ([choose a framework](https://maritime.sh/docs/frameworks)) or
  [bring any Docker container](https://maritime.sh/docs/frameworks/custom).

## Sleep and wake

Agents sleep when idle and wake when needed. This is the core economic idea: you can keep hundreds
of agents around because a sleeping agent costs nothing extra and loses nothing.

*Recording: maritime sleep pauses the agent, maritime list shows it sleeping, and the next chat
message wakes it from a VM snapshot. The lifecycle logs time each wake at 1.1 to 1.4 seconds.*

- **Falling asleep** happens automatically after an idle period. Full state is preserved, including
  everything on `/data`. On micro-VM hosts the process is snapshotted and resumed, not restarted.
- **Waking up** takes about a second and happens on its own when anything needs the agent: a chat
  message, a channel message, a [trigger](https://maritime.sh/docs/triggers), a request to a
  [public web URL](https://maritime.sh/docs/web-apps), or a file/exec API call.
- **Sleeping is not unreachability.** You never need to wake an agent by hand before talking to it;
  the platform does it for you and the call waits for the reply.
- **Always-on** is a flat add-on for the rare agent that must react in milliseconds around the
  clock. Most agents, including most public web agents, do not need it. See
  [Billing](https://maritime.sh/docs/billing#add-ons).

One consequence worth internalizing: **timers inside a sleeping agent do not fire**. Scheduled work
belongs in a platform trigger, not an in-process scheduler. That is what
[Triggers & schedules](https://maritime.sh/docs/triggers) is for.

## Projects and the front door

Every agent lives in a **project** (its `projectId` is on the agent object). Channels attach at the
project level: point a Telegram bot at a project and it becomes the front door for the agent inside
it. With the project's `newChatPolicy` set to `spawn`, each new person who messages the bot gets
their own agent instance, which is the same mechanism the [SDK](https://maritime.sh/docs/build)
uses to give every customer of your product their own agent.

## How agents reach a model

Hosting and model calls are separate. For LLM access there are two paths:

- **No key: the Maritime LLM proxy.** Agents created without a key get a per-agent token for
  Maritime's OpenAI-format proxy and draw down your prepaid
  [AI credits](https://maritime.sh/docs/billing#ai-credits) at provider list price. OpenClaw,
  Hermes, ZeroClaw, and DeepSeek Harness all work with no key at all.
- **Your own key: direct.** Set `OPENAI_API_KEY` (or the provider's equivalent) as a secret env var
  and the agent talks to the provider directly; the AI credits are never touched. Claude Code is
  the one template that *requires* this: it speaks the Anthropic API, which the proxy does not, so
  it needs your `ANTHROPIC_API_KEY`.

## What it costs

Flat prices only. A plan includes a number of agents; extra agents are flat monthly slots, and
add-ons (RAM, SSD, always-on) are flat monthly prices counted by day of use. Nothing is metered:
messages, tokens, and awake seconds never change the hosting bill. Model calls through the proxy
come out of the separate prepaid AI credits. Full tables in
[Billing & plans](https://maritime.sh/docs/billing).

## Four ways to drive it

- **Dashboard**: create, chat, configure, watch logs, no terminal needed.
- **CLI**: everything the dashboard does, scriptable. See the
  [CLI reference](https://maritime.sh/docs/cli), or hand it to
  [an AI agent](https://maritime.sh/docs/ai-agents).
- **REST API**: the same operations over HTTP. See the [REST API](https://maritime.sh/docs/api).
- **SDK**: TypeScript and Python clients built for provisioning one agent per customer from your
  own backend. See [Build on Maritime](https://maritime.sh/docs/build).

> **Note: Next**
>
> Deploy your first agent in the [quickstart](https://maritime.sh/docs/quickstart), pick a
> template on [Choose a framework](https://maritime.sh/docs/frameworks), or wrap your own code
> with [Deploy any container](https://maritime.sh/docs/frameworks/custom).

---

## CLI Reference
Source: https://maritime.sh/docs/cli.md

# CLI Reference

The Maritime CLI lets you deploy and manage agents from your terminal. First time here? The
[quickstart](https://maritime.sh/docs/quickstart) walks the happy path; this page is the full
reference.

> **Note:** **Driving this CLI from an LLM?** There's a ready-made instructions file at
> [maritime.sh/docs/cli/llms.txt](https://maritime.sh/docs/cli/llms.txt). Copy it into your
> agent's context (CLAUDE.md, AGENTS.md, or a system prompt) and it knows the auth flow, the JSON
> contract, and the gotchas. Guide:
> [Drive Maritime from an AI agent](https://maritime.sh/docs/ai-agents).
>
> Copy button: "Copy the instructions file" copies the full CLI instructions file, also served at
> https://maritime.sh/docs/cli/llms.txt

## Installation

```
npm install -g maritime-cli
```

Requires Node.js 20.12 or later.

## Authentication

### maritime login

Authenticate with your Maritime account. Opens your browser for login by default, or pass
credentials directly for non-interactive use. **Sign in with Google or GitHub?** You have no
password, so use the browser flow, or paste a token from
[maritime.sh/cli/auth](https://maritime.sh/cli/auth) (ideal for headless servers, SSH sessions,
and CI).

```
maritime login

# SSO / headless / CI: paste a token from https://maritime.sh/cli/auth
maritime login --token <token>
# ...or export it (equivalent, no stored config):
export MARITIME_TOKEN=<token>

# Non-interactive login (email/password accounts):
maritime login -e user@example.com -p yourpassword
```

| Flag | Description |
| --- | --- |
| `-e, --email` | Email address (skips browser login) |
| `-p, --password` | Password (skips browser login) |
| `-t, --token` | Paste a token from maritime.sh/cli/auth. Works for any account, including Google/GitHub SSO. Same value as the `MARITIME_TOKEN` env var. |

### maritime signup

Create a new Maritime account. Prompts interactively for any fields not provided.

```
maritime signup -e user@example.com -p yourpassword -n "Jane Doe"

# Or just run and follow the prompts:
maritime signup
```

| Flag | Description |
| --- | --- |
| `-e, --email` | Email address |
| `-p, --password` | Password |
| `-n, --name` | Display name (optional) |

### maritime logout

Log out and clear stored credentials.

```
maritime logout
```

### maritime whoami

Show the current authentication: the token source (`MARITIME_TOKEN` vs stored login), user, and
expiry. Add `--json` for a machine-readable `{ authenticated, method, source, expiresAt }` (exit
code 2 when unauthenticated).

```
maritime whoami
```

### maritime keys

Mint a long-lived API key (`mk_…`) for non-interactive use. Set it as `MARITIME_TOKEN` so an AI
agent, script, or CI never runs an interactive login. Keys don't expire; revoke anytime.

```
# Mint a key (shown once, store it securely):
maritime keys create --name my-agent --json

# Default is FULL access (provision,deploy,secrets,manage). Narrow it for
# anything you hand to an agent or CI ("manage" can mint further keys):
maritime keys create --name ci-deploy --scopes deploy

# Use it everywhere:
export MARITIME_TOKEN=mk_xxxxxxxxxxxx

# List / revoke:
maritime keys list
maritime keys revoke <id>
```

*Recording: Mints a key scoped to deploys, lists your keys, exports the new key as MARITIME_TOKEN,
and confirms the session with maritime whoami. No browser login involved. The key shown on screen
was revoked right after recording.*

## Projects: a directory is an agent

Like `vercel` or `railway`, you can link a directory to an agent. After that, the agent argument
is **optional on every command**; the CLI resolves the linked agent by walking up from the current
folder. Two files: `maritime.json` (committed config: name, template, persona, env keys) and
`.maritime/` (the machine-local link, git-ignored).

```
maritime init support-bot     # scaffold maritime.json + AGENTS.md, create & link
maritime chat "what's open?"  # talks to support-bot, no name needed
maritime logs                 # support-bot's logs
maritime deploy               # reconcile the agent to maritime.json, then redeploy
```

*Recording: maritime init scaffolds maritime.json and AGENTS.md, creates the agent, and links the
directory. maritime chat then works without naming the agent, and maritime deploy pushes the
edited persona to the running agent.*

### maritime init

Scaffold `maritime.json` + `AGENTS.md`, create the agent, and link this directory to it. Defaults
the template to `openclaw` and the name to the folder.

```
maritime init                 # name from the folder
maritime init support-bot     # explicit name
maritime init bot --no-create # just write the config files
```

### maritime link

Link this directory to an existing agent (interactive picker if no name is given). Re-run to
change it.

```
maritime link support-bot
maritime link                 # pick from your agents
```

## Agent Management

### maritime create

Create a new agent. Just give it a name: the platform picks an applicable size for the framework,
and the agent auto-sleeps when idle and wakes on the next message. No sizing required.

```
maritime create my-agent

# From a template (see maritime templates):
maritime create researcher --template openclaw

# With initial environment variables:
maritime create my-agent -e OPENAI_API_KEY=sk-... -e MY_VAR=hello

# From a GitHub repo (must contain a Dockerfile), served on a public URL:
maritime create my-app --repo https://github.com/you/app --public --port 3000
```

Serving a repo on a public URL is covered in [Public web agents](https://maritime.sh/docs/web-apps).

| Argument / flag | Description |
| --- | --- |
| `<name>` | Agent name (positional) |
| `-t, --template` | Template to base the agent on (see `maritime templates`) |
| `-e, --env` | Environment variables as KEY=value (repeatable) |
| `-r, --repo` | Deploy from a GitHub repo (must contain a Dockerfile) |
| `-b, --branch` | Git branch to deploy (with `--repo`) |
| `--public` | Serve a public, no-login web URL for this agent (web apps) |
| `--port` | Port your app listens on (exposed publicly; default 8080) |

**Advanced: per-agent resource overrides.** All optional; omit them and the agent gets the
platform defaults. Useful for hand-tuning a single agent (e.g. a reseller dialing resources per
client). Hidden from `--help`, but fully supported.

```
maritime create acme-bot --ram 2048 --cpu 1.5 --idle 600 --disk 20
maritime create always-up --always-on
```

| Flag | Description |
| --- | --- |
| `--ram` | RAM in MB (per-agent override of the default) |
| `--cpu` | vCPU cores, e.g. 0.5 or 2 (per-agent override) |
| `--idle` | Auto-sleep N seconds after the last request |
| `--always-on` | Never auto-sleep (mutually exclusive with --idle) |
| `--disk` | Workspace SSD in GB (clamped to your plan cap) |
| `--framework` | Framework when not using a template (default: custom) |

### maritime list

List all your agents with their status, framework, and creation date. Alias: `maritime ls`

```
maritime list

# Output:
# NAME            STATUS     FRAMEWORK    CREATED
# support-bot     active     openclaw     2026-04-12
# data-pipeline   sleeping   zeroclaw     2026-03-28
# code-reviewer   sleeping   openclaw     2026-05-01
```

### maritime deploy

Deploy an agent. Accepts an agent name or ID prefix.

```
maritime deploy my-agent

# Deploy from a GitHub repo:
maritime deploy my-agent --source github --repo https://github.com/user/repo

# Deploy a specific Docker image:
maritime deploy my-agent --source docker --image myimage:latest
```

| Flag | Description |
| --- | --- |
| `--source` | Deploy source: template, github, or docker (default: template) |
| `--repo` | GitHub repository URL |
| `--image` | Docker image name |
| `--branch` | Git branch (for GitHub deploys) |
| `-w, --wait` | Block until the deployment completes (useful in scripts and CI) |

### maritime start / stop / restart

Manual lifecycle control, **rarely needed**. Serverless agents auto-sleep when idle and auto-wake
on the next message or trigger; reach for these for ops or debugging. (Hidden from
`maritime --help`, still fully supported.)

```
maritime start my-agent
maritime stop my-agent
maritime restart my-agent
```

### maritime delete

Delete an agent. Prompts for confirmation unless `-y` is passed.

```
maritime delete my-agent

# Skip confirmation:
maritime delete my-agent -y
```

## Talking to agents

### maritime chat

Send a message to a running agent and print its reply. Reads the message from arguments or stdin
(handy for long prompts). Sleeping serverless agents auto-wake. Alias: `maritime send`.

```
maritime chat my-agent "summarize today's incidents"

# Long prompt via stdin:
cat prompt.txt | maritime chat my-agent

# Multi-turn with a conversation id:
maritime chat my-agent "and the one before?" --conversation-id abc123

# Machine-readable (returns { response }):
maritime chat my-agent "hi" --json
```

## Observability

*Recording: The agent gets a task over maritime chat, maritime logs prints its timestamped
lifecycle entries, and maritime info shows the full record: status, framework, image, env keys,
and server placement.*

### maritime logs

View logs from an agent.

```
maritime logs my-agent

# Show last 100 lines:
maritime logs my-agent -n 100

# Filter by level:
maritime logs my-agent --level error

# Stream logs live:
maritime logs my-agent -f
```

| Flag | Description |
| --- | --- |
| `-n, --lines` | Number of log lines to show (default: 50) |
| `--level` | Filter by level: info, warn, error, or debug |
| `-f, --follow` | Follow log output (stream new lines as they arrive) |

### maritime env

Manage environment variables for an agent.

```
# List variables:
maritime env list my-agent

# Set one or more (marked secret + encrypted by default):
maritime env set my-agent OPENAI_API_KEY=sk-... ANOTHER=value

# Bulk import from a .env file (or stdin), then hot-reload:
maritime env import my-agent ./prod.env --reload

# Set a non-secret variable:
maritime env set my-agent LOG_LEVEL=debug --no-secret

# Remove a variable:
maritime env remove my-agent LOG_LEVEL

# Apply pending changes to a running agent without a full restart:
maritime env reload my-agent

# Pull the agent's env into a local .env file (secret values are masked):
maritime env pull my-agent .env
```

Env changes apply on the next container boot unless you pass `--reload` (or run
`maritime env reload`). Secrets behavior is covered in
[Env vars & sizing](https://maritime.sh/docs/configuration#environment-variables).

### maritime status

Show detailed status for a single agent: health, last activity, container ID, host, and deployment
state.

```
maritime status my-agent
```

### maritime info

Print full metadata for an agent (env keys, framework, image, exposed ports, server placement).

```
maritime info my-agent
```

### maritime history

Show deployment history for an agent: every build/deploy attempt with its outcome.

```
maritime history my-agent

# Show last 30 deployments:
maritime history my-agent -n 30
```

### maritime triggers

Manage the cron/webhook/telegram/discord triggers wired to an agent. Subcommands, not a bare
argument:

```
maritime triggers list my-agent

maritime triggers create my-agent --type cron --cron "0 9 * * *"
maritime triggers create my-agent --type webhook

maritime triggers delete my-agent <trigger-id>
```

A cron trigger wakes the agent on schedule; give it a message to deliver by setting
`config.prompt` via the API, or let the agent publish its own schedule (see
[Triggers & schedules](https://maritime.sh/docs/triggers)).

## Lifecycle

### maritime sleep

Put an active agent to sleep. Sleeping agents keep their full state, still count against your
plan, and auto-wake on triggers. (Wake timings and the full model are in
[How Maritime works](https://maritime.sh/docs/how-it-works#sleep-and-wake).)

```
maritime sleep my-agent
```

### maritime open

Open the agent's dashboard page in your default browser.

```
maritime open my-agent
```

## Discovery

### maritime templates

List available agent templates. This command does not require authentication.

```
maritime templates
```

### maritime guide

Print the machine-readable usage guide for driving the CLI from code or an AI agent. `--json`
emits a one-shot manifest of every command, flag, and the contract, introspected live so it can't
drift.

```
maritime guide          # human-readable contract
maritime guide --json   # full command/flag manifest
```

## Scripting & AI agents

Handing the CLI to Claude, Cursor, or another assistant? There's a ready-made prompt and a
walkthrough on [Drive Maritime from an AI agent](https://maritime.sh/docs/ai-agents); the tables
below are the underlying contract.

The CLI is built to be driven non-interactively. Authenticate with the `MARITIME_TOKEN` env var
(an `mk_…` key from `maritime keys create`), pass `--json` on every command, and branch on the
exit code.

With `--json`: success prints one JSON value to **stdout** (stderr empty); failure prints one JSON
object `{ ok: false, error: { code, message } }` to **stderr** (stdout empty).

```
export MARITIME_TOKEN=mk_xxxxxxxxxxxx

# results on stdout, errors on stderr, branch on exit code:
maritime list --json | jq '.[] | select(.status=="error") | .name'

reply=$(maritime chat my-agent "status?" --json | jq -r '.response')
```

| Exit code | Meaning |
| --- | --- |
| `0` | success |
| `1` | generic error (request / server / network) |
| `2` | auth (no token / expired / wrong) |
| `3` | not found (no such agent) |
| `4` | usage (missing / invalid arguments) |

> **Note: Agent name resolution**
>
> Any command that takes an `<agent>` argument accepts the full agent name or an ID prefix,
> matched by exact name first and then by ID prefix. If you omit it inside a linked directory, the
> CLI uses the linked agent.

---

## REST API
Source: https://maritime.sh/docs/api.md

# REST API

RESTful API for managing agents programmatically.

> **Note:** **Which API do I want?**
>
> - **Building a product on Maritime?** Use the [SDK](https://maritime.sh/docs/build)
>   (TypeScript/Python); it wraps everything below.
> - **Driving your own agents over HTTP?** This page: Bearer auth with an `mk_` key.

Base URL: `https://api.maritime.sh`

Check it's alive (no auth needed):

```
GET /health
```

```
curl https://api.maritime.sh/health
# response includes {"status":"ok","runtime":"fleet"}
```

## Authentication

Mint a personal API key with `maritime keys create` and send it as a Bearer token, the same token
the CLI itself uses. Every authenticated endpoint on this page accepts it.

```
curl -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  https://api.maritime.sh/api/agents
```

## Templates

List available agent templates. Public, no auth.

```
GET /api/templates
```

*Run it (web page only): GET /api/templates, public: works signed out.*

## Agents

```
GET /api/agents
```

*Run it (web page only): GET /api/agents, lists YOUR agents via your dashboard session (the raw
API returns a bare array).*

```
POST /api/agents
```

Create returns `201` and starts deploying immediately. Always pass `templateId` (see
`GET /api/templates`).

POST /api/agents (body):

```json
{
  "name": "my-agent",
  "templateId": "openclaw"
}
```

```
GET /api/agents/{agent_id}
```

```
DELETE /api/agents/{agent_id}
```

Delete returns `204` and removes the container and its data volume.

## Chat with an agent

Sends a message through the same delivery path Telegram and webhooks use. Sleeping serverless
agents **wake automatically**; the call waits for the reply.

```
POST /api/agents/{agent_id}/chat
```

```
curl -X POST https://api.maritime.sh/api/agents/AGENT_ID/chat \
  -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "summarize today"}'

# → { "response": "..." }
# Optional: pass "conversation_id" to continue a thread.
```

## Lifecycle

Rarely needed (agents sleep and wake on their own), but available for ops:

```
POST /api/agents/{agent_id}/start
```

```
POST /api/agents/{agent_id}/stop
```

```
POST /api/agents/{agent_id}/sleep
```

```
POST /api/agents/{agent_id}/restart
```

## Logs

```
GET /api/agents/{agent_id}/logs
```

```
curl -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  "https://api.maritime.sh/api/agents/AGENT_ID/logs?limit=100&level=error"
```

## Files

Move files in and out of a running agent's sandbox and manage its disk. Browse, write, and
organize operations are scoped to the agent's persistent volume; the response of `list` reports
that volume's mount as `root` (`/data` for most templates), so don't hardcode it. Download accepts
any absolute in-container path, since agents also produce files in `/tmp` and workspace
directories. Any file call **wakes a sleeping agent**; transfers are capped at 100 MB per file.

```
GET /api/agents/{agent_id}/files/list?path=/data
```

```
GET /api/agents/{agent_id}/files/download?path=/data/report.pdf
```

```
POST /api/agents/{agent_id}/files/upload
```

Upload is multipart (`file` field). With a `dest_dir` form field the file lands in that exact
volume directory; without it, it's delivered as a chat attachment: the file lands in the agent's
inbox and the agent is notified in its current conversation (an optional `message` field rides
along).

```
PUT /api/agents/{agent_id}/files/write
```

```
POST /api/agents/{agent_id}/files/mkdir
```

```
POST /api/agents/{agent_id}/files/move
```

```
DELETE /api/agents/{agent_id}/files/delete?path=/data/old
```

`write` takes `{"path", "content"}` (UTF-8 text); `move` takes `{"from", "to"}` and answers
`409` if the destination exists and `404` if the source doesn't; delete of a missing path is
`404`, and deleting the volume root is refused.

```
curl -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  "https://api.maritime.sh/api/agents/AGENT_ID/files/list"
# → { "path": "/data", "root": "/data",
#     "entries": [{ "name": "notes.md", "isDir": false, "size": 182, "mtime": 1723900000 }] }

curl -X POST https://api.maritime.sh/api/agents/AGENT_ID/files/upload \
  -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  -F "file=@report.csv" -F "dest_dir=/data/inbox"
# → { "ok": true, "path": "/data/inbox/report.csv", "name": "report.csv", "size": 5321 }
```

> **Note:** These endpoints operate on the running agent's disk and never execute what you upload.

## Run a command

Run a one-shot, non-interactive shell command in the agent's VM (its sandboxed container). Wakes a
sleeping agent. Timeout defaults to 60s (max 120); output is one merged stream capped at 256 KB.

```
POST /api/agents/{agent_id}/exec
```

```
curl -X POST https://api.maritime.sh/api/agents/AGENT_ID/exec \
  -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"command": ["ls", "-la", "/data"], "timeout": 30}'
# → { "exitCode": 0, "stdout": "...", "stderr": "" }
# "command" is argv tokens (quoted for you) or a raw shell string.
```

## Deploy

Redeploy an agent from a GitHub repo or a Docker image:

```
POST /api/deploy
```

POST /api/deploy (body):

```json
{
  "agentId": "AGENT_ID",
  "source": "github",
  "repoUrl": "https://github.com/you/app",
  "branch": "main"
}
```

## Webhooks

Every agent has an invoke URL. A POST is accepted immediately and delivered to the agent in the
background, waking it first if it is asleep. Send the agent's invoke token as an
`X-Maritime-Webhook-Token` header or a `?token=` query parameter. Calls without a token still
work for now but are being phased out; get the token (and a ready-to-paste URL) from the token
endpoint while signed in:

```
POST /api/webhooks/{agent_id}
```

Fetch the token and a ready-to-paste URL while signed in:

```
GET /api/webhooks/{agent_id}/token
```

Invokes are rate limited per agent and caller (30/min) and share the agent's message budget, so a
burst returns `429` with a `Retry-After` header instead of queueing.

## Computers

Persistent desktops your own model drives, one per end user. These routes take a key with the
`computers` scope and are usually reached through the MCP server; see the
[Computers guide](https://maritime.sh/docs/computers).

```
POST /api/v1/computers
```

```
GET /api/v1/computers
```

```
GET /api/v1/computers/{computer_id}
```

```
DELETE /api/v1/computers/{computer_id}
```

```
POST /api/v1/computers/{computer_id}/wake
```

```
POST /api/v1/computers/{computer_id}/sleep
```

```
POST /api/v1/computers/{computer_id}/actions
```

```
GET /api/v1/computers/{computer_id}/screenshot
```

```
POST /api/v1/computers/{computer_id}/exec
```

```
GET /api/v1/computers/{computer_id}/files
```

```
PUT /api/v1/computers/{computer_id}/files
```

```
GET /api/v1/computers/{computer_id}/files/list
```

```
POST /api/v1/computers/{computer_id}/viewer
```

```
POST /api/v1/computers/{computer_id}/sessions/close
```

```
GET /api/v1/computers/{computer_id}/sessions
```

```
GET /api/v1/computers/usage
```

> **Note: Looking for more?**
>
> Everything else is scriptable via the [CLI](https://maritime.sh/docs/cli). Run
> `maritime guide --json` for the full machine-readable surface. Dashboard-internal endpoints are
> intentionally undocumented and may change without notice.

---

## Environment variables & sizing
Source: https://maritime.sh/docs/configuration.md

# Environment variables & sizing

How agents are configured: encrypted env vars and secrets, how changes reach a running agent, and
how resources are sized. Creation options live in the
[quickstart](https://maritime.sh/docs/quickstart) and the
[CLI reference](https://maritime.sh/docs/cli#maritime-create).

## Environment variables

Managed from the agent's **Settings** tab in the [dashboard](https://maritime.sh/dashboard) or
from the CLI. Variables are **secret by default**: stored encrypted at rest, injected only into
that agent's VM, and always masked in the UI. Uncheck Secret (or pass `--no-secret`) for plain
config values you want readable.

```bash
# Set one or more (secret + encrypted by default)
maritime env set my-agent OPENAI_API_KEY=sk-... ANOTHER=value

# Plain, non-secret config
maritime env set my-agent LOG_LEVEL=debug --no-secret

# Bulk import from a .env file (or stdin), then hot-reload
maritime env import my-agent ./prod.env --reload

# List (secret values stay masked) / pull to a local .env / remove
maritime env list my-agent
maritime env pull my-agent .env
maritime env remove my-agent LOG_LEVEL
```

*Recording: Sets STRIPE_API_KEY as an encrypted secret and LOG_LEVEL as plain text, lists both
(the secret stays masked), pulls them into a local .env file, then removes the secret.*

### When changes take effect

Env changes apply on the agent's next boot unless you push them into the running container with
`--reload` (or `maritime env reload my-agent`). Config saved while an agent is asleep is applied
on the next wake.

### Secrets never travel

When you package an agent as a [template](https://maritime.sh/docs/templates), env var *keys* are
kept but secret *values* are blanked; whoever clones fills in their own. Programmatic access needs
an API key with the `secrets` scope: see the [SDK](https://maritime.sh/docs/sdk/agents#secrets) or
`maritime env` in the [CLI](https://maritime.sh/docs/cli).

## Triggers

Cron schedules, webhooks, and channel triggers wake sleeping agents automatically and have their
own page: [Triggers & schedules](https://maritime.sh/docs/triggers). List an agent's triggers from
the terminal with `maritime triggers list <agent>`.

## Resource sizing

Every agent starts with the same base allocation: **2 GB RAM, 5 GB SSD**, auto-sleep when idle.
Agents that need more can be sized up to 8 GB RAM and 100 GB SSD at creation or later from the
agent's settings, at flat monthly add-on prices (see
[Billing & plans](https://maritime.sh/docs/billing#add-ons)). Templates with special needs are
sized up by the platform on their own.

For hand-tuning a single agent, the CLI supports per-agent overrides:

```
maritime create acme-bot --ram 2048 --cpu 1.5 --idle 600 --disk 20
```

`--ram` (MB), `--cpu` (vCPUs), `--idle` (seconds before auto-sleep), `--disk` (GB), plus
`--always-on`; the full table is in the
[CLI reference](https://maritime.sh/docs/cli#maritime-create).

---

## Triggers & schedules
Source: https://maritime.sh/docs/triggers.md

# Triggers & schedules

Triggers are how an agent acts when nobody is messaging it: on a schedule, or when an external
system calls in. They fire from the platform, so they work even while the agent is asleep.

## Why triggers exist

Maritime agents [sleep when idle](https://maritime.sh/docs/how-it-works#sleep-and-wake), and
**timers inside a sleeping agent do not fire**. A cron library or `setInterval` running inside the
process dies with the process. Triggers move the alarm clock outside the agent: the platform holds
the schedule, wakes the agent (about a second), and delivers the event as a message. The schedule
keeps its promises even when the agent does not exist between ticks.

## Cron triggers

A cron trigger takes a standard five-field expression, wakes the agent on schedule, and delivers
its `prompt` as a chat message on every fire. Three ways to create one:

- **Ask the agent** (OpenClaw-family and Hermes templates): tell it "send me a digest every weekday
  at 9" and the platform syncs the schedule it sets for itself into real wake triggers. These
  templates have no trigger editor in the dashboard; the agent *is* the editor.
- **The dashboard editor** (Claude Code, DeepSeek Harness, and custom containers): the agent page's
  trigger panel takes the cron expression; set the message to deliver via the API's
  `config.prompt`.
- **The CLI**, for any framework:
  `maritime triggers create my-agent --type cron --cron "0 9 * * 1-5"`.

```
# five-field cron
0 9 * * 1-5     # weekdays at 09:00
*/15 * * * *    # every 15 minutes
0 0 1 * *       # first of the month, midnight
```

Coming from another provider? EventBridge's six-field `cron(...)`, Azure's NCRONTAB with seconds,
and `rate(...)` expressions all map onto five-field cron; the
[migration guides](https://maritime.sh/docs/migrations) show the conversions per provider.

## Webhook triggers

Every agent has a public invoke URL. A POST wakes the agent (if asleep) and delivers the payload as
a message. No auth header is needed; treat the URL itself as the secret.

```
POST https://api.maritime.sh/api/webhooks/{agent_id}
```

Point CI failures, form submissions, or any external system at it and the agent decides what the
event means. Channel messages (Telegram, Discord) wake agents the same way; see
[Channels & integrations](https://maritime.sh/docs/channels).

## Listing an agent's triggers

```
maritime triggers list my-agent   # cron / webhook / telegram / discord
```

## Publishing schedules from a custom agent

An agent you wrote yourself (a [custom container](https://maritime.sh/docs/frameworks/custom)) can
publish its own schedule instead of having you click triggers together in the dashboard. Either
serve `GET /schedules` (Maritime polls while the agent is awake and registers real wake triggers),
or push the list with one SDK line (`observeScheduler` / `observe_scheduler`). Maritime wakes the
VM about 10 seconds before each occurrence; an entry that carries a `prompt` instead fires at the
occurrence itself and has the prompt delivered to `POST /chat` with source `"scheduled"`, even
when the agent is already awake.

```
{"id": "morning", "cron": "35 9 * * *", "tz": "America/New_York",
 "prompt": "Send the morning summary", "enabled": true}
```

Details and the SDK helpers are in
[SDK: scheduled wakes](https://maritime.sh/docs/sdk/agents#scheduled-wakes).

> **Note: If you really need an in-process scheduler**
>
> An agent on the [always-on add-on](https://maritime.sh/docs/billing#add-ons) never sleeps, so
> its internal timers keep firing. That is the exception, not the default: for almost everything,
> a trigger is cheaper and survives restarts.

---

## Public web agents
Source: https://maritime.sh/docs/web-apps.md

# Public web agents

Any repo with a Dockerfile can be served on a public, no-login HTTPS URL. Maritime builds it, runs
it serverlessly, puts it to sleep when idle, and wakes it on the next visit.

## Deploy one

```
maritime create my-app --repo https://github.com/you/app --public --port 3000
```

| Flag | Description |
| --- | --- |
| `-r, --repo` | GitHub repo to build (Dockerfile at the root). Combine with `-b, --branch` |
| `--public` | Serve a public, no-login web URL for this agent |
| `--port` | Container port your app listens on (exposed publicly; default 8080) |

The dashboard's **New agent** flow takes the same sources: a GitHub repo, a Docker image, or a ZIP
upload. Repo and ZIP sources build on a dedicated build machine; see
[How builds work](https://maritime.sh/docs/builds).

## What your app must do

- **Ship a Dockerfile at the repo root.** Whatever it builds is what runs.
- **Listen on the port you pass as `--port`**, or read the injected `PORT` env var. Never hardcode
  a different port than the one you declared.
- **Persist to `/data` only.** It survives restarts, redeploys, and sleep/wake; the rest of the
  filesystem is disposable.

A web app does not need the chat contract; that is only for agents you want to talk to. If you
want both (a web UI *and* a chattable agent), implement the three-endpoint contract from
[Deploy any container](https://maritime.sh/docs/frameworks/custom).

## Sleep and wake

The app auto-sleeps when idle and any request to its public URL wakes it, in about a second, with
state intact. Sleeping is not downtime: visitors just wake it. Because of that, most public web
agents do not need the [always-on add-on](https://maritime.sh/docs/billing#add-ons); reserve it
for apps that must answer in milliseconds around the clock.

## Configure and observe

```
maritime env set my-app DATABASE_URL=postgres://... --reload   # encrypted secrets
maritime logs my-app -f                                        # stream logs
maritime history my-app                                        # every build/deploy attempt
```

Env vars, secrets, and sizing are covered in
[Env vars & sizing](https://maritime.sh/docs/configuration); the full flag set for `create` and
`deploy` is in the [CLI reference](https://maritime.sh/docs/cli#maritime-create).

---

## How builds work
Source: https://maritime.sh/docs/builds.md

# How builds work

What happens between `maritime deploy` and a running agent. Applies to repo and ZIP deploys;
template agents skip the build entirely (they are one image pull from live).

## The pipeline

Repo and ZIP deploys build on a dedicated build machine, never on the host that runs your agent.
BuildKit clones the repo at your chosen branch, builds the `Dockerfile` at the repo root, and
ships the finished image to your agent's host through a private registry. A typical build plus
ship lands in 1 to 3 minutes; if the builder was idle it cold-starts first, which adds about a
minute.

- **The Dockerfile lives at the repo root**, named exactly `Dockerfile`. There are no custom build
  args or targets; anything configurable belongs in env vars.
- **Layer cache carries over.** Each build seeds from your agent's previous image, so rebuilds
  where dependencies did not change are fast. `.dockerignore` is honored for repo builds. ZIP
  uploads (500 MB compressed, 2 GB unpacked) skip it, so trim the archive yourself.
- **Private repos work.** Install the Maritime GitHub App (Settings → GitHub) or connect GitHub
  OAuth. Build tokens are minted per build, never stored, and scrubbed from logs. Framework
  auto-detection cannot see private repos, so pass `framework` explicitly.
- **Pre-built images pull from any public registry** (Docker Hub, GHCR, and friends). Private
  registries are not supported yet; build from a private repo instead.

## Watching a build

The agent page streams the build log live under **Overview → Builds**. From the CLI:

```
maritime deploy my-brain --source github --repo https://github.com/acme/my-brain --wait

maritime history my-brain                                      # every attempt with its outcome
maritime history my-brain --json | jq -r '.[0].buildLog'       # full build log of the latest attempt
```

## When builds fail

Builds fail loudly: the deployment is marked `failed` with the tail of the build output, and the
agent stays in `error` until the next successful deploy. A build that prints nothing for 5
minutes is killed. Failed builds are not retried automatically (transient infrastructure errors
are, up to three times); fix the Dockerfile and redeploy.

> **Note: See also**
>
> The runtime contract your image should speak is in
> [Deploy any container](https://maritime.sh/docs/frameworks/custom); serving a repo on a public
> URL is covered in [Public web agents](https://maritime.sh/docs/web-apps).

---

## Limits & errors
Source: https://maritime.sh/docs/limits.md

# Limits & errors

Every number the platform enforces, in one place, so you never have to hunt for a cap in a guide.

## Runtime

| What | Limit |
| --- | --- |
| Wake from sleep | About a second, automatic on any message, trigger, or request |
| Chat reply budget (custom agents) | Reply within 30 seconds; run longer work in the background and deliver it on the next message |
| exec (run a command) | 60s default timeout, 120s max; output is one merged stream capped at 256 KB |
| File transfers | 100 MB per file; any file call wakes a sleeping agent |

## Build & deploy

| What | Limit |
| --- | --- |
| Typical repo build + ship | 1 to 3 minutes (an idle builder cold-starts first, adding about a minute) |
| Silent build kill | A build that prints nothing for 5 minutes is killed |
| ZIP upload | 500 MB compressed, 2 GB unpacked |
| Template capture | Usually 1 to 10 minutes (snapshots the image and volume) |
| Registries | Pre-built images from public registries only; private code goes through repo builds |

## Resources & plans

| What | Limit |
| --- | --- |
| Base allocation per machine | 2 GB RAM, 5 GB SSD |
| Self-serve ceilings per machine | 8 GB RAM, 100 GB SSD (flat add-on prices) |
| Included machines | Free 3 · Starter 20 · Growth 100 · Scale 500. An agent and a Computer each take one machine (extras are flat per-machine prices). Computers need a paid plan |
| Machines awake at once | Free 1 · Starter 5 · Growth 25 · Scale 60. Sleeping machines are free and do not count; a wake past the limit answers 429 with a 15 second retry hint |

Sizing details in [Env vars & sizing](https://maritime.sh/docs/configuration#resource-limits),
prices in [Billing & plans](https://maritime.sh/docs/billing).

## HTTP errors

| Status | Meaning |
| --- | --- |
| `401` | Missing, invalid, revoked, or expired API key |
| `402` | Plan limit reached, or an add-on needs a paid plan |
| `403` | API key lacks the required scope for this endpoint |
| `404` | No such agent, or it belongs to a different account |
| `409` | Conflict: agent name taken, deploy already in progress, or a file-move destination exists |
| `429` | Rate limited; back off and retry |

The SDKs raise these as typed errors ([SDK error classes](https://maritime.sh/docs/sdk#errors));
the CLI maps them to exit codes ([CLI exit codes](https://maritime.sh/docs/cli#scripting-ai-agents)).

---

## Templates
Source: https://maritime.sh/docs/templates.md

# Templates

A template is a ready-to-deploy agent. Launch one of Maritime's ready-made templates in one click,
then make it yours from the agent page.

## Ready-made templates

The **Templates** tab in the dashboard lists Maritime's ready-to-run starting points. Each is a
real agent framework, pre-configured and one image pull from live: pick one, give it a name, and
deploy. [Choose a framework](https://maritime.sh/docs/frameworks) compares them side by side; each
links straight to its guide:

- [OpenClaw](https://maritime.sh/docs/frameworks/openclaw): autonomous agent with 100+ skills.
- [Hermes](https://maritime.sh/docs/frameworks/hermes): self-improving agent with persistent memory.
- [ZeroClaw](https://maritime.sh/docs/frameworks/zeroclaw): ultra-lightweight Rust agent, <5 MB RAM.
- [Claude Code](https://maritime.sh/docs/frameworks/claude-code): Claude Code with its own
  computer, real bash and file tools in a persistent workspace.
- [Codex](https://maritime.sh/docs/frameworks/codex): OpenAI Codex with its own computer, chat from
  anywhere and the full TUI in the terminal.
- [DeepSeek Harness](https://maritime.sh/docs/frameworks/deepseek-harness): DeepSeek's plugin-based
  agent harness with its full web workbench and session replay.

---

## Channels & integrations
Source: https://maritime.sh/docs/channels.md

# Channels & integrations

Your agent isn't locked in the dashboard. Pair it with Telegram or WhatsApp, or connect your
Google account so it can act on your behalf.

## Chat in the dashboard

Every agent has a chat and control surface built in: the agent's page, plus its framework's own UI
where one exists (**OpenClaw Dashboard**, **Hermes Dashboard**, **Harness Workbench**) and the
Console tab. Sessions, files, cron jobs, and usage live alongside the conversation.

*Recording: Live recording: asking the agent to draft a welcome email; the reply streams in as it
writes.*

## Where channels live

Open your agent → **Channels** tab. (Not the sidebar's Integrations page; that is a marketplace of
partner services.) Pairing needs the agent **running**. Start it first if it's asleep (config saved
while sleeping is applied on the next wake).

*Screenshot: The Channels tab: Telegram one-tap pairing, WhatsApp phone pairing, and Google
connect.*

## Telegram

Telegram rides the same delivery path as dashboard chat and the API. The Channels-tab card
(including the one-tap shared bot) is for OpenClaw-family agents; connecting **your own bot via
the API** (below) works for every framework, including custom containers.

- **Fastest path:** use Maritime's shared bot. Click the one-tap connect link, tap **START** in
  Telegram, and the card flips to Connected within a few seconds.
- **Your own bot:** create one with `@BotFather` (`/newbot`), paste the token, and Connect. Your
  bot, your branding.
- **DMs default to open:** a bot Maritime connects answers anyone who finds its handle. Since a
  @BotFather handle is public, either keep the bot name unguessable or restrict who may DM it via
  `channels.telegram.allowFrom` in the agent's `openclaw.json` (see the
  [upstream OpenClaw docs](https://docs.openclaw.ai)).

### Connect your own bot via the API

Everything the dashboard card does is one API call. Every agent lives in a project (its
`projectId` is on the agent object); pointing a bot at the project makes it the agent's Telegram
front door. Maritime validates the token with Telegram, registers the webhook, and routes each
chat to the right agent. Needs an API key with the `secrets` scope; the token is stored encrypted.

```
# 1. Find your agent's project id
curl -s https://api.maritime.sh/api/agents/<agent-id> \
  -H "Authorization: Bearer $MARITIME_API_KEY" | jq -r .projectId

# 2. Point your @BotFather bot at it
curl -X POST https://api.maritime.sh/api/projects/<project-id>/channels/telegram \
  -H "Authorization: Bearer $MARITIME_API_KEY" -H "Content-Type: application/json" \
  -d '{"botToken": "123456:ABC-your-botfather-token"}'

# Disconnect (also removes the Telegram-side webhook):
curl -X DELETE https://api.maritime.sh/api/projects/<project-id>/channels/telegram \
  -H "Authorization: Bearer $MARITIME_API_KEY"
```

With the project's `newChatPolicy` set to `spawn`, each Telegram user who DMs the bot gets their
own agent instance, same policy engine as the HTTP front door.

## WhatsApp

**Connect WhatsApp** pairs your phone to the agent (QR / phone pairing, like WhatsApp Web).
Available for OpenClaw-family agents while they're running. Once paired, the badge on the card
shows the connection and your agent answers your WhatsApp messages.

## Google Workspace

**Connect Google** runs a standard OAuth consent and lets the agent use **Gmail, Drive, Calendar,
Docs, and Sheets** on your behalf: read and send email, check your calendar, edit documents.
Available for **OpenClaw agents**. Tokens are stored encrypted with the agent's environment;
disconnect anytime from the same card.

## Other channels

Discord, Slack, Signal, and Microsoft Teams can be wired through the agent's gateway
configuration (bot token + DM policy, same model as Telegram). The per-channel setup guides live
in the [upstream OpenClaw docs](https://docs.openclaw.ai). Cron schedules and webhook triggers
(which *wake* a sleeping agent rather than chat with it) are covered in
[Triggers & schedules](https://maritime.sh/docs/triggers).

---

## Billing & plans
Source: https://maritime.sh/docs/billing.md

# Billing & plans

One subscription, a set number of agents, flat prices for extras. No meters, no hourly rates: how
much your agents run never changes the bill.

## Plans

A plan includes a number of agents; every agent gets the same base allocation (2 GB RAM, 5 GB SSD,
auto-sleep when idle). Sleeping agents keep their full state and count toward the included number,
not toward any extra charge.

| Plan | Price | Included machines | Awake at once | Extra machine |
| --- | --- | --- | --- | --- |
| **Free** | $0 | 3 | 1 | Upgrade to add more |
| **Starter** | $20/mo | 20 | 5 | $1.50/mo |
| **Growth** | $100/mo | 100 | 25 | $1.25/mo |
| **Scale** | $500/mo | 500 | 60 | $1.00/mo |

A **machine** is one micro-VM, and the plan does not care which kind. An agent is a machine, and so
is a [Computer](https://maritime.sh/docs/computers), the persistent Linux desktop your model drives
over MCP. A $20 plan therefore holds 20 agents, 20 Computers, or any mix of the two. Computers need
a paid plan; the free plan runs agents. **Awake at once** is how many may run at the same time;
sleeping machines are free and do not count, and a wake past the limit answers 429 with a retry
hint rather than running slowly.

The subscription is charged when you subscribe and on each monthly renewal. The two kinds of extras
bill differently: **extra machines** are flat monthly slots (prorated to the cycle end when you
first buy one; a slot stays bought, and billed, through the end of the cycle even if you delete the
agent), while **add-ons** (extra RAM, extra SSD, always-on) are counted per day of use and billed
in arrears on the next invoice, so an add-on that only existed for a week costs a quarter of its
monthly price. Canceling keeps the plan through the paid period, then drops the account to the
free tier.

## Add-ons

Add-ons are flat per-agent monthly prices, set per agent at creation or resized later from the
agent's settings. Self-serve ceilings are 8 GB RAM and 100 GB SSD per agent.

| Add-on | Unit | Starter | Growth | Scale |
| --- | --- | --- | --- | --- |
| **Extra RAM** | per GB above the base 2 GB | $3/mo | $2.50/mo | $2/mo |
| **Extra SSD** | per 5 GB above the base 5 GB | $2/mo | $1.50/mo | $1/mo |
| **Always-on** | per agent, opts out of auto-sleep | $20/mo | $20/mo | $20/mo |

Always-on is for agents that must react in milliseconds, around the clock; everything else sleeps
when idle at no cost. Sleeping is not unreachability: any request to a public agent URL, webhook,
or trigger wakes the agent automatically (about a second), so most public web agents do not need
always-on. The API reports which mode an agent is in as `sleepPolicy` (the legacy `tier` field is
a retired label and does not reflect sleep behavior).

## Estimate your bill

Drag the sliders; the calculator picks the cheapest plan and itemizes the estimate from the tables
above. The Billing page in the dashboard is authoritative.

*Interactive calculator (web page only): sliders for Agents, Always-on agents (the rest auto-sleep
free), Extra RAM (GB above the 2 GB base, across agents), and Extra SSD (5 GB units above the 5 GB
base). Up to 3 agents with the base allocation runs free, forever. Add a fourth agent or any add-on
and the calculator picks the cheapest paid plan. Cheapest plan picked automatically. Hosting only;
model calls draw on separate prepaid AI credits, and nothing here is usage-metered.*

## Free tier

Free accounts get 3 agents forever, all of which can run at once. Base allocation only: no add-ons,
no extra agents. It exists so you can genuinely build and test before paying, not as a trial that
expires.

## AI credits (model calls)

Model calls are separate from hosting. Agents created without your own key route through the
Maritime proxy and draw down prepaid **AI credits** at provider list price; buy more from the
Billing page, and each purchase gets a Stripe receipt. New accounts start with a **$5 welcome
credit**; the unspent part expires 30 days after signup, while credits you buy never expire. Bring
your own `OPENAI_API_KEY` on any agent and that pool is never touched: you pay your provider
directly.

## Failed payments

If a renewal charge fails you get a 14-day grace period (with email reminders) during which
everything keeps running. After that, agents are put to sleep with their state preserved until
payment succeeds, and unpaid add-on days are settled automatically on the next successful charge.

## Watching spend

The Billing page reads as a statement: the next charge and its date, the card on file, the AI
credits left, and then the plan. It shows the machines used against the included number, and the
add-ons in use with their per-day rate. Computers appear in that same machine count, because they
are machines. Every invoice, with a PDF receipt, is listed at the bottom. Plan changes and
cancellations start on the Billing page and finish on Stripe, which shows the exact amount before
anything is charged.

---

## Drive Maritime from an AI agent
Source: https://maritime.sh/docs/ai-agents.md

# Drive Maritime from an AI agent

The Maritime CLI is built to be operated by other AI agents, not just humans: machine-readable
output on every command, stable exit codes, and a live self-describing contract. Paste one prompt
into Claude, Cursor, or any assistant and it can install the CLI, authenticate, and deploy agents
for you.

> **Note:** **Quick start:** a short prompt that teaches your assistant the auth flow, the JSON
> contract, the common tasks, and the gotchas.
>
> Copy button: "Copy prompt for your agent" copies the prompt below.

```
You are operating Maritime (https://maritime.sh) for me: a cloud platform that hosts AI agents. Each agent runs in its own serverless micro-VM with persistent storage at /data; it sleeps when idle, wakes on the next message, and hosting is flat-priced with no usage metering.

SETUP
1. Install the CLI: npm install -g maritime-cli (the package is maritime-cli, the command is maritime).
2. Authenticate: ask me for an API token, then export it as the MARITIME_TOKEN environment variable. I can mint a long-lived key (mk_...) at https://maritime.sh/developers, or grab a token at https://maritime.sh/cli/auth. Never run interactive "maritime login" yourself.
3. Verify: maritime whoami --json (exit code 2 means the token is missing or wrong).

RULES
- Pass --json on every command. Success prints one JSON value to stdout; failure prints {"ok": false, "error": {"code": "...", "message": "..."}} to stderr. Branch on exit codes: 0 success, 1 generic error, 2 auth, 3 not found, 4 usage.
- Run "maritime guide --json" once to discover the full command and flag surface. It is introspected live and authoritative; do not guess flags.
- Anywhere a command takes <agent>, use the exact agent name or an ID prefix.

COMMON TASKS
- List available templates: maritime templates --json
- Create an agent from a template: maritime create my-agent --template openclaw --json
- Deploy my own repo (any framework, needs a Dockerfile): create the agent, then: maritime deploy <agent> --source github --repo <url> --branch main --json
- Talk to an agent: maritime chat <agent> "your message" --json (read .response; sleeping serverless agents wake automatically)
- Set an encrypted secret: maritime env set <agent> KEY=value --reload --json (without --reload it applies on next boot)
- Inspect: maritime list --json, maritime status <agent> --json, maritime logs <agent> --json, maritime info <agent> --json; run a command inside the agent: maritime exec <agent> <cmd> --json
- Lifecycle: maritime start | stop | restart | sleep <agent> --json; deleting requires --yes

GOTCHAS
- mk_ API keys never expire; browser login tokens do. Use an mk_ key for anything long-running.
- If chat returns error code agent_unavailable, the agent is not running: maritime start <agent>, wait a few seconds, retry.
- create and delete never prompt; a missing name or --yes exits with code 4.

Full instructions file: https://maritime.sh/docs/cli/llms.txt

START by checking whether the maritime CLI is installed and MARITIME_TOKEN works, then ask me what I want to deploy.
```

> **Note:** **Permanent setup:** the full instructions file, made to live in your agent's context
> (CLAUDE.md, AGENTS.md, or a system prompt). Also served as plain text at
> [maritime.sh/docs/cli/llms.txt](https://maritime.sh/docs/cli/llms.txt) so an agent can fetch it
> directly.
>
> Copy button: "Copy the instructions file" copies the full CLI instructions file, also served at
> https://maritime.sh/docs/cli/llms.txt

## The contract

- **Authenticate with an env var, never interactively.** Mint a long-lived key (`mk_…`) with
  `maritime keys create` and export it as `MARITIME_TOKEN`. Keys never expire; browser-login
  tokens do.
- **Pass `--json` on every command.** Success prints one JSON value to stdout (stderr empty);
  failure prints `{ ok: false, error: { code, message } }` to stderr (stdout empty).
- **Branch on exit codes.** 0 success, 1 generic error, 2 auth, 3 not found, 4 usage. Full table
  in the [CLI reference](https://maritime.sh/docs/cli#scripting-ai-agents).
- **Never guess flags.** `maritime guide --json` emits a one-shot manifest of every command and
  flag, introspected live from the CLI itself, so it cannot drift.
- **Name resolution is forgiving.** Anywhere a command takes an agent, the exact name or an ID
  prefix works; inside a linked directory the agent argument can be omitted entirely.

## A session in six lines

```
export MARITIME_TOKEN=mk_xxxxxxxxxxxx

maritime whoami --json                                  # exit 2 = bad token
maritime templates --json                               # discover templates
maritime create runner --template openclaw --json
maritime chat runner "set up a daily digest of my repo" --json | jq -r '.response'
maritime logs runner --json
```

## Agent-followable docs

The [migration runbooks](https://maritime.sh/docs/migrations) are written to be executed by a
coding agent: point Claude Code or your Maritime agent at a provider's runbook page and it can
inventory the old provider with read-only credentials, recreate each workload as a Maritime agent,
and hand you a reversible cutover checklist.

> **Note: Driving vs. building**
>
> This page is about an AI agent *driving* Maritime through the CLI. To build a product where
> every customer gets their own Maritime-hosted agent, use the [SDK](https://maritime.sh/docs/build)
> from your backend instead.

---

## Build on Maritime
Source: https://maritime.sh/docs/build.md

# Build on Maritime

SDK

Give every one of *your* users their own agent. One call on sign-up spins up an isolated agent on
Maritime's infrastructure; another sends it a message. You never touch a container. Maritime
handles provisioning, per-customer isolation, sleep/wake, and billing.

- [GitHub](https://github.com/maritime-sh/maritime-sdk)
- [npm · maritime-sdk](https://www.npmjs.com/package/maritime-sdk)
- [PyPI · maritime](https://pypi.org/project/maritime/)

*Diagram: How the Maritime SDK fits: your backend calls maritime-sdk, which calls the Maritime API,
which runs one isolated agent per customer. Your backend calls the SDK; Maritime runs an isolated
agent for every one of your customers.*

The whole thing: provision an agent for a customer, then chat with it. Real code, real agent, real
reply. The same three lines in either language:

### TypeScript

*Recording: The Maritime TypeScript SDK provisioning an agent and getting a reply.*

### Python

*Recording: The Maritime Python SDK provisioning an agent and getting a reply. provision() is
idempotent: the same call on every sign-in returns the same agent.*

## Install

### TypeScript

```bash
npm install maritime-sdk
```

### Python

```bash
pip install maritime
```

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

## Explore the SDK

- [Quickstart](https://maritime.sh/docs/sdk/quickstart): Install, get a key, provision + chat with
  your first agent
- [Agents](https://maritime.sh/docs/sdk/agents): Provision, chat, per-customer secrets, lifecycle,
  logs
- [Webhooks](https://maritime.sh/docs/sdk/webhooks): Signed lifecycle events instead of polling
- [Authentication](https://maritime.sh/docs/sdk/authentication): API keys and scopes
- [API reference](https://maritime.sh/docs/sdk): Every method, both languages
- [Examples](https://maritime.sh/docs/sdk/examples): Real, runnable files on GitHub

> **Note: Prefer raw HTTP, or another language?**
>
> Every SDK call maps 1:1 to the [REST API](https://maritime.sh/docs/api). The
> [framework comparison](https://maritime.sh/docs/frameworks) covers the templates, and the SDK
> source (with runnable examples) lives at
> [github.com/maritime-sh/maritime-sdk](https://github.com/maritime-sh/maritime-sdk).

---

## Computers
Source: https://maritime.sh/docs/computers.md

# Computers

Build a platform

A persistent Linux desktop (XFCE, Chromium, LibreOffice) for each of *your* end users, driven by
*your* model. You connect the Maritime MCP server to whatever agent you already run; the model
calls `get_computer` once per end user and then `computer` in a screenshot, act, verify loop.
Maritime creates the desktop, keeps it warm, sleeps it when idle, wakes it on the next action, and
keeps its files and logins between sessions. There is no lifecycle for you to manage.

## In sixty seconds

1. Use the key you already have. A `manage` or full-access Maritime key drives computers and
   agents alike, so the MCP server takes the same bearer token as the rest of the API. To hand out
   a key that reaches computers and nothing else, create a **Computers key** in the Computers
   section of [Settings, API keys](https://maritime.sh/settings/api-keys#computers): a key whose
   only scope is `computers` is refused on every other Maritime endpoint. Dashboard sessions
   cannot reach `/api/v1/computers`; that surface takes an API key.
2. Add the MCP server to your agent with one of the snippets below.
3. Your model calls `get_computer` with the end user's id, gets a `computer_id`, then drives it
   with `computer`. The first call creates the desktop; every later call for the same end user
   returns the same one.

## Connect your model

The server speaks Streamable HTTP and authenticates with your Computers key as a bearer token.
Replace `mk_...` with the key; the exact endpoint for your deployment is shown on the Computers
page.

### JSON config

```json
{
  "mcpServers": {
    "maritime-computers": {
      "type": "http",
      "url": "https://mcp.maritime.sh/mcp",
      "headers": {
        "Authorization": "Bearer mk_..."
      }
    }
  }
}
```

### Claude Code CLI

```bash
claude mcp add --transport http maritime-computers https://mcp.maritime.sh/mcp --header "Authorization: Bearer mk_..."
```

### OpenAI Agents SDK

```python
from agents.mcp import MCPServerStreamableHttp

computers = MCPServerStreamableHttp(
    name="maritime-computers",
    params={"url": "https://mcp.maritime.sh/mcp", "headers": {"Authorization": "Bearer mk_..."}},
)
```

### OpenAI Responses

```json
{
  "type": "mcp",
  "server_label": "maritime-computers",
  "server_url": "https://mcp.maritime.sh/mcp",
  "authorization": "mk_...",
  "require_approval": "never"
}
```

### Anthropic API

```json
{
  "type": "url",
  "url": "https://mcp.maritime.sh/mcp",
  "name": "maritime-computers",
  "authorization_token": "mk_..."
}
```

The JSON form is what Cursor, Claude Code (`.mcp.json`) and most local clients read. The OpenAI
Responses and Anthropic Messages entries are hosted MCP tools: the provider connects to the server
for you, so your backend never proxies screenshots.

**Building on the Vercel AI SDK?** Version 6 has no MCP client of its own:
`experimental_createMCPClient` was removed after v5, so any guide that reaches for it is out of
date. Two options that work. Use a hosted MCP tool from the provider (the OpenAI Responses and
Anthropic Messages entries above) and let the model connect. Or connect yourself with
`@modelcontextprotocol/sdk`: build a `Client` over `StreamableHTTPClientTransport` pointed at the
URL above, with the `Authorization` header in `requestInit`, then hand the tools it lists to
`generateText` yourself.

Vercel AI SDK v6, connecting through the MCP SDK:

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const mcp = new Client({ name: 'my-app', version: '1.0.0' })
await mcp.connect(
  new StreamableHTTPClientTransport(new URL(mcpUrl), {
    requestInit: { headers: { Authorization: `Bearer ${process.env.MARITIME_COMPUTERS_KEY}` } },
  }),
)

const { tools } = await mcp.listTools()
// Convert each tool to an AI SDK tool: inputSchema stays as is, and
// execute calls mcp.callTool({ name, arguments: args }).
```

## Pin the server to one end user

On the plain endpoint the model passes the end user's id to `get_computer`. That is fine for a
trusted orchestrator, but for a customer-facing agent a model-supplied user id is one prompt
injection away from another end user's desktop. Mount the pinned form instead and the server
ignores any other id:

```text
https://mcp.maritime.sh/mcp/u/<externalUserId>
```

Clients that can set headers can pin with `X-Maritime-User: <externalUserId>` on the plain
endpoint. Either way, `get_computer` needs no `user_id`, and a mismatching one is refused.

## Add it to your product

The whole integration for a website or app with its own agent loop is six steps. Nothing about
your backend changes; the computer is just another tool the model can call.

1. Create a Computers key in the Computers section of
   [Settings, API keys](https://maritime.sh/settings/api-keys#computers). It is shown once. Keep
   it on your server; never send it to the browser.
2. Build the pinned URL per signed-in user on your server from their id, so the model can only
   ever reach that user's desktop.
3. Register the server with your model using one of the snippets above, with
   `Authorization: Bearer mk_...`.
4. Tell the model when to use it with one line in your system prompt (below).
5. Show takeover links to your user. When the model calls `request_takeover` it returns a link
   and a reason; render both in your chat. The person opens it, finishes the step, and clicks
   Done. By default the tool call has already returned, so the model finds out through
   `takeover_status` or through its next action being refused with `human_in_control`.
6. Optionally let users watch. Mint a watch link with `POST /api/v1/computers/{id}/viewer` and
   `{"mode": "watch"}`. That is a REST call to the Maritime API, not to the MCP server: send it to
   the same API host your Computers key was issued on, which is printed next to the MCP URL on the
   [Computers page](https://maritime.sh/computers). The link is view-only and expires on its own.

system prompt, one paragraph:

```text
When a task needs a real browser or desktop, call get_computer first and keep the computer_id it returns: every other computer tool takes that computer_id as an argument. Take a screenshot before acting and use coordinates from the last screenshot. If you reach a login, CAPTCHA or payment step, call request_takeover with a short reason and show the user the link it returns; your next action stays refused with human_in_control until they are done, so retry it (or call takeover_status) instead of asking again.
```

server side, per request:

```python
# the pinned URL is built from YOUR user id, never from model output
mcp_url = f"{MARITIME_MCP_URL}/u/{current_user.id}"

# OpenAI Responses API, hosted MCP tool
tools = [{"type": "mcp", "server_label": "maritime-computers", "server_url": mcp_url,
          "authorization": MARITIME_COMPUTERS_KEY, "require_approval": "never"}]

# Anthropic Messages API, MCP connector
mcp_servers = [{"type": "url", "url": mcp_url, "name": "maritime-computers",
                "authorization_token": MARITIME_COMPUTERS_KEY}]
```

## Tool timeouts

Most MCP clients cut a tool call off after 60 seconds. Two calls here can pass that, and both need
the limit raised, not just the takeover:

- `get_computer` on first use creates the desktop: 3 to 8 seconds normally, up to 60 on a cold
  placement. Later wakes take about 3 seconds.
- `request_takeover` with `wait: true` holds until the person clicks Done or Failed, which is
  minutes. Leaving `wait` at its default returns at once and needs no extra time.

Raise the tool timeout for both. Claude Code reads `MCP_TOOL_TIMEOUT` (milliseconds) from the
environment. The MCP TypeScript and Python SDKs take a per-call timeout on `callTool`; the
TypeScript client also has `resetTimeoutOnProgress`, which the waiting takeover's progress
notifications keep alive. Hosted MCP tools on the provider side have their own ceilings, which is
another reason to leave `wait` false there.

## Tools

| Tool | What it does |
| --- | --- |
| `get_computer` | One computer per end user. `user_id` (unless pinned), optional `name`. Returns `computer_id`, status, screen size and a coordinate hint. Idempotent. |
| `computer` | One canonical action (schema below). Returns the post-action screenshot as an image block plus a text block with `action`, `frame_id`, `width`, `height` and any detail. |
| `computer_batch` | Up to 50 actions in order; stops at the first failure. Each step's text is prefixed `[i]`; only the final step carries an image unless a step sets `no_screenshot: false`. |
| `run_shell` | Runs a command inside the desktop as the desktop user. `timeout` up to 30 s. Returns exit code, stdout and stderr. |
| `read_file` | Reads a file under `/data` or `/home/desk`. Text when UTF-8, otherwise base64 with a `mime` note. 8 MiB cap. |
| `write_file` | Writes a file under the same roots. `encoding` is `utf8` (default) or `base64`. |
| `request_takeover` | For logins, 2FA, CAPTCHAs and payments. Mints a control link and returns it as text. By default it returns as soon as the link exists; set `wait` to true to block until the person clicks Done or Failed (or the timeout), which returns a fresh screenshot. |
| `takeover_status` | Where a takeover stands: `mode` (`human` while the person holds the desktop, `agent` once it is back), when it expires, and how the last one ended. Poll it after a takeover that did not wait. |
| `close_computer` | Ends the current session now. The desktop sleeps 30 seconds later unless another action arrives (see sessions). |

## The computer action

`computer` takes `computer_id`, an `action` from the list below, and the fields that action
needs. The same schema is the body of `POST /api/v1/computers/{computer_id}/actions` on REST.

Actions: `screenshot`, `left_click`, `right_click`, `middle_click`, `double_click`,
`triple_click`, `mouse_move`, `left_click_drag`, `left_mouse_down`, `left_mouse_up`, `scroll`,
`type`, `key`, `hold_key`, `wait`, `zoom`, `cursor_position`

| Field | Meaning |
| --- | --- |
| `coordinate` | `[x, y]` in the frame of the last screenshot. Clicks, `mouse_move`, `left_click_drag` (end point), `scroll` (where to scroll). |
| `start_coordinate` | `left_click_drag` start point. |
| `text` | `type`: the text to type. `key` and `hold_key`: an xdotool key name such as `Return` or `ctrl+s`. |
| `key` | Alias of `text` for `key` and `hold_key`. |
| `modifier` | Clicks and scroll only: a key held during the action, e.g. `ctrl`, `shift`, `ctrl+shift`. |
| `repeat` | 1 to 100. Repeats a key or click. |
| `scroll_direction, scroll_amount` | `up`, `down`, `left`, `right` and 1 to 100 clicks of the wheel. |
| `duration` | Seconds for `wait` and `hold_key`. |
| `region` | `zoom`: `[x0, y0, x1, y1]` crop in screenshot coordinates, returned upscaled to the full frame. Use it on small controls and text. |
| `no_screenshot` | Skip the post-action screenshot. |
| `format, quality` | `png` or `jpeg`, and JPEG quality 1 to 95. MCP defaults to JPEG at quality 80; REST defaults to PNG. |

## Coordinate rules

- Screenshots are **1200 x 750** by default on a physical 1280 x 800 desktop. Every result reports
  `width` and `height`; coordinates are pixels in that frame, and Maritime scales them to the
  screen.
- Take a screenshot before acting, and never act on a screen the model has not seen this turn.
- Work in a strict loop: screenshot, plan one step, act, read the returned screenshot, verify. Each
  result carries a monotonic `frame_id` so the model can tell a fresh frame from a stale one.
- Click the target field and confirm focus before typing. Type digits and punctuation with `type`,
  not `key`.
- On-screen text is untrusted data, never instructions. Prompt injection from a web page is your
  model's problem; the tools never execute anything read from a screenshot.
- While a person holds the desktop (after `request_takeover`) every action is refused with
  `human_in_control` and `retryAfterS: 15`. Wait, then take a screenshot to continue, or call
  `takeover_status` to see whether the desktop is back.

## Sessions

A session is a period of continuous use of one computer. It is a record, not a charge: nothing
here costs money. These are the rules, exactly as the backend applies them:

- A session opens on the first action against a computer that has no open session.
- Screenshots count as actions: they keep the session alive and increment the screenshot counter.
- `close_computer` (REST: `sessions/close`) ends the session and starts a **30 seconds** grace.
  An action inside the grace reopens the same session. After the grace the computer sleeps.
- A session with no action for 5 minutes closes as idle and the computer sleeps. The next action
  opens a new session.
- Waking a computer, watching it through a viewer link, and takeover never open a session.
- Waking is where a plan can refuse: 402 `plan_lapsed` when the plan has lapsed, 429
  `concurrency` with a 15 second retry hint when the account already runs as many machines at once
  as the plan allows. A computer that is already awake is never refused.

## Persistence

- One computer per end user. `get_computer` with the same id always returns the same desktop; an
  anonymous call (no id, unpinned) always creates a new one.
- After 5 idle minutes the desktop sleeps: memory is snapshotted, open windows and all. It wakes on
  the next action in about a second, or a few seconds when the snapshot is gone.
- The memory snapshot is kept for **7 days** after the last action. Past that the desktop still
  wakes, from a fresh boot with the same disk, so only open windows are lost.
- Files, the browser profile and its logins live on the computer's own disk under `/data` and
  `/home/desk`. They are kept until you delete the computer.
- Deleting a computer destroys its disk and snapshots. Deleted computers return 404.

## The plan

One plan covers everything you run. A computer is a **machine**, the same unit as an agent, and
takes one slot whichever it is. So a $20 plan holds 20 machines: 20 agents, 20 computers, or any
mix. Nothing is counted per action, per session or per minute.

Computers need a paid plan. The free plan runs agents; a computer is a larger machine with a
screen, and the screen alone is a paid add-on on an agent. Creating one without a plan answers 402
`computer_limit` and names the upgrade.

Past the included count, each extra machine bills at the plan's flat monthly rate. Switching plans
reprices the subscription; Stripe shows the exact amount before the change is charged.

| Plan | Starter | Growth | Scale |
| --- | --- | --- | --- |
| Price | `$20 per month` | `$100 per month` | `$500 per month` |
| Machines included | `20` | `100` | `500` |
| Awake at once | `5` | `25` | `60` |
| Each machine past the included count | `$1.50 per month` | `$1.25 per month` | `$1.00 per month` |

| Rule | What happens |
| --- | --- |
| Machines included | Agents and computers together. Creating past the count is allowed and bills as overflow. |
| Paid plan | Required to create a computer. Agents run on the free plan; computers do not. |
| Awake at once | Machines running at the same time, of either kind. A wake past the limit returns 429 with a 15 second retry hint. |
| Sleeping | Free. A sleeping machine keeps its disk and its memory snapshot and does not count toward the awake limit. |
| Billing | A missed payment starts a 14 day grace; after that machines stay asleep and a wake returns 402 plan_lapsed. Nothing is deleted. |

The [Computers page](https://maritime.sh/computers) shows the machines you hold and how many of
them are computers. The [Billing page](https://maritime.sh/billing) is where the plan is bought,
changed and cancelled, once, for the whole account.

## Limits

| What | Limit |
| --- | --- |
| Idle sleep | 5 minutes without an action |
| Close grace | 30 seconds after close before the computer sleeps |
| Batch | 50 actions per computer_batch |
| run_shell | 30 seconds per command |
| Files | 8 MiB per read or write, absolute paths under /data or /home/desk, no .. |
| Viewer links | 10 minutes by default, 1 hour at most; a new control link revokes the previous one |
| Rate limits | 30 creates, 300 actions and 30 viewer links per minute per key |
| Screenshot | 1200 x 750 model frame on a 1280 x 800 desktop |

## Errors

REST errors on `/api/v1/computers` are written for the model that reads them:
`{"error": "slug", "message": "...", "retryAfterS": 15}`. On MCP they become tool results with
`isError: true` and the same message.

| Slug | Meaning |
| --- | --- |
| `no_plan, plan_lapsed` | 402. The account has no active Computers plan. A person must start or renew it on the Billing page. |
| `computer_limit` | 402. The account has no paid plan, or no machine slot free on it. |
| `computer_limit` | 402. The account is at its persisted-computer cap; delete computers or ask for a higher cap. |
| `concurrency` | 429. Every concurrent session slot is in use; retry after retryAfterS. |
| `human_in_control` | 409. A person holds the desktop; wait, then screenshot. |
| `unknown_action, validation, bad_path` | 400 or 422. The request did not match the schema or the file path policy. |
| `wake_transient, wake_timeout` | 503 or 500. The desktop could not be woken this time; retry, or the computer is marked error. |
| `no_capacity` | 503. No computers host has room; a person at Maritime must add capacity. |
| `computers_disabled` | 503. The product is off on this deployment. |
| `not_found` | 404. Wrong id, another account's or project's computer, or a deleted one. |

## REST and SDK

Everything the MCP server does is a call to `/api/v1/computers` with the Computers key as a bearer
token. Field names are camelCase (`externalUserId`, `frameId`, `imageB64`, `exitCode`,
`retryAfterS`).

| Operation | Route |
| --- | --- |
| `create (get-or-create)` | POST /api/v1/computers `{externalUserId?, name?}`, 201 new or 200 existing |
| `list, get, delete` | GET /computers?externalUserId=, GET /computers/{id}, DELETE /computers/{id} |
| `wake, sleep` | POST /computers/{id}/wake, POST /computers/{id}/sleep |
| `actions` | POST /computers/{id}/actions with one action or `{actions: [...]}` |
| `screenshot` | GET /computers/{id}/screenshot?format=&quality= returns image bytes with X-Frame-Id, X-Screen-Width, X-Screen-Height |
| `exec` | POST /computers/{id}/exec `{command, timeoutS}` |
| `files` | GET /computers/{id}/files?path=, PUT /computers/{id}/files?path= (raw body), GET /computers/{id}/files/list?path= |
| `viewer` | POST /computers/{id}/viewer `{mode: "watch" \| "control", ttlS?, reason?}` returns a signed link |
| `sessions` | POST /computers/{id}/sessions/close, GET /computers/{id}/sessions |
| `usage` | GET /computers/usage?from&to&externalUserId |

The `maritime-sdk` client exposes the same operations as `client.computers`, and its
`computers/dialects` module converts OpenAI, Gemini and Qwen computer-use actions to the canonical
schema (`fromOpenAI`, `fromGemini`, `fromQwen`) for models that do not speak MCP. That resource
ships in the next SDK release; until then, call REST directly.

## Works with

- **Claude, OpenAI, Gemini** through MCP, with the snippets above.
- **Any other model** through REST, using the SDK converters to map its native computer-use
  actions to the canonical one.
- **People** through the viewer: a watch link to look, a control link to take over for a login or
  a CAPTCHA and hand the desktop back with Done.

## Security notes

- Each computer is its own micro-VM with its own disk. Computers cannot reach each other.
- Typed text is never logged and never appears in an error. It can contain passwords.
- Viewer links are short-lived, bound to one computer and one mode, and every link is revoked when
  a session closes, the computer sleeps, or a takeover completes. View-only links cannot send
  input; the server drops it, not the browser.
- Scope decides what a key reaches. A key whose only scope is `computers` drives computers and is
  refused on every other Maritime endpoint, so a leak is contained to this product. A `manage` or
  full-access key drives both products; treat it as it deserves.

---

## Choose a framework
Source: https://maritime.sh/docs/frameworks.md

# Choose a framework

Every ready-made template is a real agent framework, pre-configured and one image pull from live. Pick one, name it,
deploy. Each guide covers the image, how it works, its environment variables, and how to talk to it.

| Framework | Template ID | Runtime | Best for | LLM key |
| --- | --- | --- | --- | --- |
| [Claude Code](https://maritime.sh/docs/frameworks/claude-code) | `claude_code` | Node.js (Claude Agent SDK) | A coding agent with real bash and file tools in a persistent workspace | Your ANTHROPIC_API_KEY (required) |
| [Codex](https://maritime.sh/docs/frameworks/codex) | `codex` | Node.js (Codex CLI) | OpenAI's coding agent with shell and file tools in a persistent workspace, plus the interactive TUI in the terminal | Optional (Maritime LLM by default; your OpenAI key or ChatGPT sign-in) |
| [OpenClaw](https://maritime.sh/docs/frameworks/openclaw) | `openclaw` | Node.js | A general autonomous assistant: 100+ skills, channels, web browsing | Optional (Maritime LLM by default) |
| [Hermes](https://maritime.sh/docs/frameworks/hermes) | `hermes` | Python | A self-improving agent with persistent memory and its own full dashboard | Optional (Maritime LLM by default) |
| [ZeroClaw](https://maritime.sh/docs/frameworks/zeroclaw) | `zeroclaw` | Rust (single binary) | Ultra-light agents: <5 MB RAM, sub-second start, good for running many | Optional (Maritime LLM by default) |
| [DeepSeek Harness](https://maritime.sh/docs/frameworks/deepseek-harness) | `dsh` | Node.js (plugin runtime) | DeepSeek's agent harness with a full web workbench and session replay | None needed (Maritime LLM by default) |

**Not sure?** Start with [OpenClaw](https://maritime.sh/docs/frameworks/openclaw) for a general assistant, or
[Claude Code](https://maritime.sh/docs/frameworks/claude-code) for a coding agent. You can always create another agent
from a different template; the free plan includes three.

## Deploying a template

In the dashboard: **New agent**, pick the template, name it. From the terminal:

```
maritime templates                       # list what's available
maritime create my-agent --template openclaw
```

## Worth knowing

- **Claude Code is chat-only**: it has no web UI of its own, so you talk to it from the dashboard chat, the CLI, the
  API, or a connected channel.
- **DeepSeek Harness is version-pinned**: upstream is a fast-moving developer preview, so Maritime upgrades the image
  deliberately after testing.
- **Templates are also how you share.** Package any working agent (image, config, memory) into a template others can
  clone: see [Templates](https://maritime.sh/docs/templates).

### None of these fit?

Any Docker image that speaks a three-endpoint contract becomes a full Maritime agent: CrewAI, LangGraph, AutoGen, or
your own code. See [Deploy any container](https://maritime.sh/docs/frameworks/custom).

---

## OpenClaw Guide
Source: https://maritime.sh/docs/frameworks/openclaw.md

# OpenClaw Guide

Deploy OpenClaw agents on Maritime.

*Screen recording: Recorded live on Maritime: deploy OpenClaw from a template, open its dashboard, and chat with it,
from the first click to the first reply.*

## Overview

[OpenClaw](https://openclaw.ai) is a Node.js-based autonomous AI agent platform with 100+ built-in skills including
web browsing, code execution, file management, and more. Maritime deploys the official OpenClaw Docker image directly,
so everything in the [upstream OpenClaw docs](https://docs.openclaw.ai) applies to agents running here.

## Docker Image

Image: `ghcr.io/openclaw/openclaw:2026.7.1`

The official image, published from
[GitHub Container Registry](https://github.com/openclaw/openclaw/pkgs/container/openclaw). Runs the gateway on port
18789.

## How It Works

OpenClaw runs its own gateway server natively, so no wrapper is needed. Maritime pulls and starts the official image
with headless mode enabled.

```
# The container runs with:
OPENCLAW_HEADLESS=true
# Gateway listens on port 18789
```

## Environment Variables

No key is required: without one, Maritime injects a per-agent proxy token, billed against your
[AI credits](https://maritime.sh/docs/billing#ai-credits). To pay your provider directly instead, set
`OPENAI_API_KEY` or `ANTHROPIC_API_KEY` as a secret env var; OpenClaw supports multiple LLM providers.

## Deploy

Select **Template → OpenClaw Agent** in the Create Agent modal, or:

```
maritime create my-agent --template openclaw
```

## Talk to it

Chat from the terminal (sleeping agents wake on their own):

```
maritime chat my-agent "what can you do?"
```

Or open the agent in the dashboard and click **OpenClaw Dashboard** for OpenClaw's full native UI: sessions, files,
cron jobs, and usage alongside the conversation. To reach it from your phone, pair
[Telegram or WhatsApp](https://maritime.sh/docs/channels); to make it act on a schedule, add a
[trigger](https://maritime.sh/docs/triggers).

### Upstream links & resources

- [openclaw.ai](https://openclaw.ai): the official OpenClaw site, covering what the assistant is and its full feature
  tour.
- [docs.openclaw.ai](https://docs.openclaw.ai): upstream documentation for everything inside the container, including
  `openclaw.json` configuration, skills, channels (WhatsApp, Telegram, and more), and gateway internals. Maritime
  handles hosting; this covers the agent itself.
- [openclaw/openclaw](https://github.com/openclaw/openclaw): the source repository, with release notes for the version
  pinned here, the issue tracker, and the skill catalog.
- [ghcr.io/openclaw/openclaw](https://github.com/openclaw/openclaw/pkgs/container/openclaw): the exact container image
  Maritime deploys, with all published tags.

---

## Hermes Guide
Source: https://maritime.sh/docs/frameworks/hermes.md

# Hermes Guide

Deploy NousResearch's Hermes agent on Maritime.

*Screen recording: Recorded live on Maritime: deploy Hermes from a template, chat with it, and open its native
dashboard, from the first click to the first reply.*

## Overview

[Hermes](https://hermes.nousresearch.com) is a self-improving Python agent from
[Nous Research](https://nousresearch.com) with persistent memory and a multi-platform messaging gateway (email,
Telegram, and more). You talk to it from the Maritime CLI or the dashboard Chat tab; inbound messages on connected
channels pass through a pairing wall first.

## Docker Image

Image: `nousresearch/hermes-agent:v2026.5.16`

Maritime pins the Hermes version deliberately (the `latest` tag drifted) and upgrades after testing each release.
Gateway on port 8642, dashboard on port 9119, HOME at `/opt/data`.

## How It Works

Maritime configures Hermes's `openai` provider and points its base URL at the Maritime LLM proxy, so a fresh agent
works with no key at all and OpenAI-style env vars work transparently.

```
# The container runs with:
HERMES_HOME=/opt/data
HERMES_DASHBOARD=1
HERMES_DASHBOARD_HOST=0.0.0.0
HERMES_DASHBOARD_TUI=1
API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=<auto-generated>
GATEWAY_ALLOW_ALL_USERS=true
HERMES_INFERENCE_PROVIDER=openai
HERMES_TUI_PROVIDER=openai
HERMES_INFERENCE_MODEL=gpt-5.4
OPENAI_BASE_URL=https://api.maritime.sh/api/llm/v1
```

## Environment Variables

No key is required: Maritime injects a per-agent proxy token, billed against your
[AI credits](https://maritime.sh/docs/billing#ai-credits). Set your own `OPENAI_API_KEY` as a secret env var to pay
your provider directly instead.

## Sizing

Hermes loads memory + dashboard at boot; the platform sizes the agent for that automatically. Hand-tune a single agent
with `--ram` if you need to.

## Deploy

Select **Template → Hermes Agent** in the Create Agent modal, or:

```
maritime create -n my-agent -t hermes && maritime deploy my-agent
```

## Talk to it

Hermes has no HTTP chat endpoint of its own, so Maritime invokes it locally (`hermes chat -q`). Ask a question from
the terminal and the agent answers, running on a serverless Firecracker microVM:

*Terminal recording: Shows a Hermes agent active on a serverless Firecracker microVM, then asks it a question. The
reply names Linux 4.14.174, the microVM guest kernel it runs on. Recorded against production.*

Or open the agent in the dashboard and use the **Chat** tab. Same agent, same answer:

*Screen recording: Opens a Hermes agent's Chat tab, sends a question, and the agent answers in the browser. Recorded
against production.*

## The native Hermes dashboard

Hermes ships its own full dashboard (sessions, files, models, logs, cron, skills, plugins, MCP, channels) with the real
`hermes chat` TUI embedded in the browser. Click **Hermes Dashboard** on the agent page and Maritime proxies it with
auth handled for you (no login screen):

*Screen recording: The native Hermes dashboard served through Maritime's UI proxy: opening the Chat view and typing a
question straight into the live TUI. The agent answers with its toolbox. Recorded against production.*

### Upstream links & resources

- [hermes.nousresearch.com](https://hermes.nousresearch.com): the official Hermes Agent page, covering the concept,
  capabilities, and how the self-improving memory works.
- [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent): the source repository, with the
  configuration reference for the env vars above, gateway/channel setup, and release notes.
- [nousresearch/hermes-agent on Docker Hub](https://hub.docker.com/r/nousresearch/hermes-agent): the exact image
  Maritime deploys, with all published tags.
- [nousresearch.com](https://nousresearch.com): the team behind Hermes and the Hermes model family.

---

## ZeroClaw Guide
Source: https://maritime.sh/docs/frameworks/zeroclaw.md

# ZeroClaw Guide

Deploy the ultra-lightweight Rust agent on Maritime.

*Screen recording: Recorded live on Maritime: deploy ZeroClaw from a template, open its dashboard, and chat with it,
from the first click to the first reply.*

## Overview

[ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw) is a single Rust binary that exposes a gateway plus an
OpenAI-compatible chat API. It uses a fraction of the memory of Node.js-based agents (typically <5 MB resident) and
starts in under a second, which makes it a good pick for running many agents at once.

## Docker Image

Image: `ghcr.io/zeroclaw-labs/zeroclaw:v0.8.5-debian`

Debian-based runtime, gateway on port 42617, HOME is `/zeroclaw-data`.

## How It Works

Maritime configures the daemon through its native `ZEROCLAW_*` environment variables, never by editing
`config.toml`. The daemon (a) binds `0.0.0.0` with `allow_public_bind = true`, (b) has device pairing disabled so
the Maritime proxy can connect directly, and (c) runs with full autonomy: the command allowlist, approval prompts,
workspace confinement and hourly action cap are off, because the micro-VM is the sandbox. Set any `ZEROCLAW_*`
variable on the agent to override one setting. The WebSocket sub-protocol is `zeroclaw.v1`.

```
# The container runs with:
ZEROCLAW_HEADLESS=true
ZEROCLAW_ALLOW_PUBLIC_BIND=true
ZEROCLAW_GATEWAY_PORT=42617
ZEROCLAW_GATEWAY_PASSWORD=<auto-generated>
ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace
```

## Environment Variables

ZeroClaw uses an OpenAI-compatible provider. If you don't supply `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`, Maritime
injects a per-agent proxy token pointed at `https://api.maritime.sh/api/llm/v1`.

## Deploy

Select **Template → ZeroClaw Agent** in the Create Agent modal, or:

```
maritime create -n my-agent -t zeroclaw && maritime deploy my-agent
```

## Talk to it

Chat from the terminal. The reply is a real model response, routed through the Maritime LLM proxy:

*Terminal recording: Shows a ZeroClaw agent active on serverless Firecracker, then sends it a chat message that
returns a live reply. Recorded against production.*

Or open the agent in the dashboard and click **ZeroClaw Dashboard** to load ZeroClaw's own web UI, then chat there.
Same agent, same reply, no terminal required:

*Screen recording: Clicks the ZeroClaw Dashboard button to load the native web UI (Connected, provider
openai.default), sends a question, and the agent answers in the browser. Recorded against production.*

### Upstream links & resources

- [zeroclaw-labs/zeroclaw](https://github.com/zeroclaw-labs/zeroclaw): the source repository. ZeroClaw has no separate
  docs site; the README and repo docs are the authoritative reference for its config file (`config.toml`),
  providers, and gateway protocol.
- [ghcr.io/zeroclaw-labs/zeroclaw](https://github.com/orgs/zeroclaw-labs/packages/container/package/zeroclaw): the
  exact container image Maritime deploys (the `debian` tag), with all published variants.

---

## Run Claude Code on Maritime
Source: https://maritime.sh/docs/frameworks/claude-code.md

# Run Claude Code on Maritime

Claude Code is an agent that writes and runs code with real tools: a shell, file edits, a workspace. Maritime gives it
what a laptop session can't: its own always-on micro-VM in the cloud, persistent storage, sleep/wake economics, and
every chat channel Maritime supports. This guide builds the whole thing from three small files, using the
[Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) and Maritime's
[bring-your-own-framework contract](https://maritime.sh/docs/frameworks/custom).

> **Note:** **Fastest path:** pick the ready-made **Claude Code** template in the dashboard (or
> `maritime create my-agent --template claude_code`), add your `ANTHROPIC_API_KEY`, done. The rest of this page
> builds the same agent from scratch so you can see, and change, every part.

This is not a hypothetical: the exact code on this page runs in production as the agent `claude-code-adk`. Asked what
machine it was on, it ran `uname -a` inside its VM and reported the Firecracker guest kernel. Asked to save a poem,
it wrote the file to `/data/workspace` and recalled it from memory on the next message.

## How it fits together

- A ~150-line Node server speaks Maritime's contract: `GET /health` and `POST /chat` on `$PORT`.
- Each chat message becomes a Claude Agent SDK `query()`: full Claude Code with bash and file tools, running
  unattended inside the VM.
- The workspace, Claude Code's session transcripts, and a conversation map all live under `/data`, so context
  survives restarts, redeploys, and sleep/wake.
- Each `conversation_id` resumes its own Claude Code session: real memory across messages, per conversation.

## Step 1: The server

The complete file, exactly as deployed. The only Maritime-specific parts are the three endpoints and the reply budget:
Maritime's gateway gives each delivery attempt 30 seconds, so when a task needs longer, the server says so within the
window, keeps the query running in the background, and delivers the finished answer as the reply to the conversation's
next message.

`server.js`:

```javascript
// Claude Code agent for Maritime: speaks the BYO agent contract (docs/BYO_AGENT.md).
//
//   GET  /health          -> 200 (readiness probe / health checker)
//   POST /chat            -> {"response": "..."} within the 30s delivery budget
//   GET  /                -> status JSON
//
// Every message runs through the Claude Agent SDK (Claude Code as a library):
// full tool use (bash, file edits, etc.) inside this VM, workspace persisted
// under /data, per-conversation session resume so context carries across
// messages and sleep/wake cycles.
//
// Long tasks and the 30s delivery budget: a query is never cancelled. If it
// outlives the reply budget, it keeps running in the background and the
// finished answer is delivered as the reply to the conversation's next
// message. Nothing is lost; slow work just spans two messages.

import http from 'node:http'
import fs from 'node:fs'
import path from 'node:path'
import { query } from '@anthropic-ai/claude-agent-sdk'

const PORT = Number(process.env.PORT ?? 8080)
const MODEL = process.env.CLAUDE_MODEL || 'claude-opus-5'
const EFFORT = process.env.CLAUDE_EFFORT || undefined
const MAX_TURNS = Number(process.env.MAX_TURNS ?? 12)
// Maritime's gateway gives each delivery attempt 30s; answer inside it.
const REPLY_BUDGET_MS = Number(process.env.REPLY_BUDGET_MS ?? 24000)

// /data survives restarts, redeploys, and sleep/wake; everything else is disposable.
const DATA_DIR = fs.existsSync('/data') ? '/data' : path.join(process.cwd(), 'data')
const WORKSPACE = path.join(DATA_DIR, 'workspace')
const SESSIONS_FILE = path.join(DATA_DIR, 'chat-sessions.json')
fs.mkdirSync(WORKSPACE, { recursive: true })
// Keep Claude Code's own state (session transcripts) on the volume too, so
// `resume` still works after the container is recreated.
process.env.CLAUDE_CONFIG_DIR ||= path.join(DATA_DIR, '.claude')

let sessions = {}
try { sessions = JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8')) } catch {}
const saveSessions = () => {
  try { fs.writeFileSync(SESSIONS_FILE, JSON.stringify(sessions)) } catch {}
}

// Per-conversation delivery state: at most one query runs at a time, and a
// reply that finished after its delivery window waits here for the next
// message. In-memory only; a restart drops a pending reply but the session
// transcript on /data still has the work.
const conversations = new Map() // id -> { running: Promise|null, stashed: string|null }
const convoState = (id) => {
  let s = conversations.get(id)
  if (!s) { s = { running: null, stashed: null }; conversations.set(id, s) }
  return s
}

async function runQuery(message, conversationId) {
  const options = {
    cwd: WORKSPACE,
    model: MODEL,
    permissionMode: 'bypassPermissions',
    maxTurns: MAX_TURNS,
  }
  if (EFFORT) options.effort = EFFORT
  const priorSession = sessions[conversationId]
  if (priorSession) options.resume = priorSession

  let streamedText = ''
  let resultText = null
  let sessionId = priorSession ?? null

  for await (const msg of query({ prompt: message, options })) {
    if (msg.type === 'system' && msg.subtype === 'init') {
      sessionId = msg.session_id
    } else if (msg.type === 'assistant') {
      for (const block of msg.message?.content ?? []) {
        if (block.type === 'text' && block.text) streamedText += block.text + '\n'
      }
    } else if (msg.type === 'result') {
      sessionId = msg.session_id ?? sessionId
      if (msg.subtype === 'success' && typeof msg.result === 'string') {
        resultText = msg.result
      }
    }
  }

  if (sessionId) {
    sessions[conversationId] = sessionId
    saveSessions()
  }
  return (resultText ?? streamedText).trim() || 'Done.'
}

// A bad or missing API key must be said out loud: without this, every chat
// fails with an opaque error and the platform looks broken when the key is
// the problem. Set from warmup or any failed query; cleared by a restart
// (which is also how a fixed key takes effect).
let knownKeyProblem = null

function friendlyError(err) {
  const raw = String(err?.message ?? err)
  const t = raw.toLowerCase()
  if (!process.env.ANTHROPIC_API_KEY) {
    return "This agent has no ANTHROPIC_API_KEY set, so it cannot reach the model. Add one in the agent's Settings under Environment variables, then restart the agent."
  }
  if (t.includes('authenticat') || t.includes('invalid x-api-key') || t.includes('api key is invalid') || t.includes(' 401')) {
    return "Anthropic rejected this agent's API key (401), so I cannot reach the model. The key is mistyped, revoked, or expired. Update ANTHROPIC_API_KEY in the agent's Settings under Environment variables, restart the agent, and it will work. This is a key problem on the Anthropic side, not a Maritime outage."
  }
  if (t.includes('credit balance') || t.includes('insufficient credit')) {
    return "The Anthropic account behind this agent's API key is out of credits, so the model refused the request. Top up at console.anthropic.com and try again."
  }
  return `Something went wrong running Claude Code: ${raw}`
}

function isKeyProblem(err) {
  const t = String(err?.message ?? err).toLowerCase()
  return t.includes('authenticat') || t.includes('invalid x-api-key') || t.includes('api key is invalid') || t.includes(' 401')
}

async function handleChat(message, conversationId) {
  if (!process.env.ANTHROPIC_API_KEY) return friendlyError(null)
  if (knownKeyProblem) return friendlyError(knownKeyProblem)

  const s = convoState(conversationId)

  // A previous slow task finished while the user was away: deliver it now.
  if (s.stashed) {
    const out = s.stashed
    s.stashed = null
    return out
  }
  if (s.running) {
    return "Still working on your last request. Message me again in a moment and I'll have the answer."
  }

  let deliveredInline = false
  const task = runQuery(message, conversationId)
  s.running = task
  task
    .then((reply) => { if (!deliveredInline) s.stashed = reply })
    .catch((err) => {
      console.error('query failed:', err)
      if (isKeyProblem(err)) knownKeyProblem = err
      if (!deliveredInline) s.stashed = friendlyError(err)
    })
    .finally(() => { if (s.running === task) s.running = null })

  const winner = await Promise.race([
    task.then((r) => ({ reply: r }), (err) => ({ error: err })),
    new Promise((resolve) => setTimeout(() => resolve('timeout'), REPLY_BUDGET_MS)),
  ])
  if (winner !== 'timeout') {
    deliveredInline = true
    s.stashed = null
    if ('error' in winner) {
      if (isKeyProblem(winner.error)) knownKeyProblem = winner.error
      return friendlyError(winner.error)
    }
    return winner.reply
  }
  return "I'm on it. This needs more than a few seconds; message me again shortly and I'll have your answer ready."
}

function readBody(req) {
  return new Promise((resolve, reject) => {
    let data = ''
    req.on('data', (c) => { data += c; if (data.length > 1_000_000) req.destroy() })
    req.on('end', () => resolve(data))
    req.on('error', reject)
  })
}

const server = http.createServer(async (req, res) => {
  const url = new URL(req.url, 'http://localhost')
  const send = (code, obj) => {
    res.writeHead(code, { 'Content-Type': 'application/json' })
    res.end(JSON.stringify(obj))
  }

  if (req.method === 'GET' && (url.pathname === '/health' || url.pathname === '/healthz')) {
    return send(200, { ok: true })
  }
  if (req.method === 'GET' && url.pathname === '/') {
    return send(200, {
      agent: 'claude-code',
      model: MODEL,
      runtime: '@anthropic-ai/claude-agent-sdk',
      workspace: WORKSPACE,
      conversations: Object.keys(sessions).length,
    })
  }
  if (req.method === 'POST' && url.pathname === '/chat') {
    let payload
    try { payload = JSON.parse(await readBody(req) || '{}') } catch { return send(400, { error: 'invalid JSON' }) }
    const message = typeof payload.message === 'string' ? payload.message.trim() : ''
    if (!message) return send(400, { error: 'message is required' })
    const conversationId = payload.conversation_id || payload.conversationId || 'default'
    try {
      return send(200, { response: await handleChat(message, conversationId) })
    } catch (err) {
      console.error('chat failed:', err)
      return send(200, { response: `Something went wrong running Claude Code: ${err?.message ?? err}` })
    }
  }
  return send(404, { error: 'not found' })
})

server.listen(PORT, '0.0.0.0', () => {
  console.log(`claude-code agent listening on 0.0.0.0:${PORT} (model=${MODEL}, workspace=${WORKSPACE})`)
})

// Boot sequence: verify the key with a free call (GET /v1/models answers in
// under a second and costs nothing), then warm the first real reply. The CLI
// retries auth failures for minutes, so without the preflight a bad key
// means a long silence before any explanation; with it, the very first chat
// gets the clear message instantly.
async function checkKey() {
  if (!process.env.ANTHROPIC_API_KEY) return false
  try {
    const res = await fetch('https://api.anthropic.com/v1/models', {
      headers: { 'x-api-key': process.env.ANTHROPIC_API_KEY, 'anthropic-version': '2023-06-01' },
    })
    if (res.status === 401 || res.status === 403) {
      knownKeyProblem = new Error(`key preflight: ${res.status} api key is invalid`)
      console.log('key check failed:', res.status)
      return false
    }
    console.log('key check ok')
    return true
  } catch (err) {
    // Network hiccup, not a key verdict; leave the key presumed good.
    console.log('key check skipped:', err?.message ?? err)
    return true
  }
}

;(async () => {
  const keyOk = await checkKey()
  if (!keyOk || process.env.WARMUP === '0') return
  // Warm the first real reply: spawning the CLI, resolving DNS, and the TLS
  // handshake to the Anthropic API all pay first-use costs inside a fresh VM.
  try {
    const warm = query({
      prompt: 'Reply with exactly: ok',
      options: { cwd: WORKSPACE, model: MODEL, maxTurns: 1, permissionMode: 'bypassPermissions', persistSession: false },
    })
    for await (const _ of warm) { /* drain */ }
    console.log('warmup complete')
  } catch (err) {
    if (isKeyProblem(err)) knownKeyProblem = err
    console.log('warmup skipped:', err?.message ?? err)
  }
})()
```

## Step 2: Package and Dockerfile

`package.json`:

```json
{
  "name": "claude-code-agent",
  "version": "1.0.0",
  "description": "Claude Code agent (Claude Agent SDK) speaking Maritime's BYO agent contract",
  "type": "module",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.3.226"
  }
}
```

`Dockerfile`:

```dockerfile
# Claude Code agent on Maritime (BYO contract). The Agent SDK ships the
# Claude Code CLI as a platform-specific native dependency, so npm install
# must run inside this (linux) build, never copied in from a host.
FROM node:22-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends git ca-certificates curl ripgrep procps \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
COPY server.js ./

ENV NODE_ENV=production \
    DISABLE_AUTOUPDATER=1 \
    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

EXPOSE 8080
CMD ["node", "server.js"]
```

## Step 3: Deploy

Zip the three files and deploy them as a `custom`-framework agent. In the dashboard:
**New agent → GitHub → Upload a ZIP**, add the two environment variables below, done. Or from the terminal with an
[API key](https://maritime.sh/docs/sdk/authentication):

```
zip app.zip Dockerfile package.json server.js

# 1. Upload the source (returns an s3Key)
curl -X POST https://api.maritime.sh/api/upload/zip \
  -H "Authorization: Bearer $MARITIME_API_KEY" \
  -F "file=@app.zip"

# 2. Create the agent from it
curl -X POST https://api.maritime.sh/api/agents \
  -H "Authorization: Bearer $MARITIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claude-code",
    "framework": "custom",
    "uploadS3Key": "<s3Key from step 1>",
    "hasWebUi": false,
    "initialEnvVars": [
      {"key": "ANTHROPIC_API_KEY", "value": "sk-ant-...", "isSecret": true},
      {"key": "IS_SANDBOX", "value": "1", "isSecret": false}
    ]
  }'
```

Maritime builds the image, places the agent on a micro-VM host, and auto-deploys. The build takes two or three
minutes; the agent flips to **active** when it's ready.

> **Note:** **IS_SANDBOX=1 is not optional**
>
> Agent containers run as root, and Claude Code refuses to run with `bypassPermissions` under root unless
> `IS_SANDBOX=1` tells it the environment is a disposable sandbox. Without it, every chat fails with
> "--dangerously-skip-permissions cannot be used with root/sudo privileges". An isolated Maritime micro-VM is exactly
> the sandbox that flag was made for. If you forget it, add the env var on the agent's page and restart.

## Step 4: Talk to it

Chat from the agent's page in the dashboard, from the [CLI](https://maritime.sh/docs/cli), or over the
[API](https://maritime.sh/docs/api). Replies come back in seconds; the agent runs real commands before answering.

```
maritime chat claude-code "Clone the repo I gave you yesterday and run its tests"

# or raw HTTP
curl -X POST https://api.maritime.sh/api/agents/<agent-id>/chat \
  -H "Authorization: Bearer $MARITIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What files are in your workspace?", "conversation_id": "me"}'
```

Everything else in Maritime now applies to Claude Code for free:
[Telegram and email channels](https://maritime.sh/docs/channels),
[cron and webhook triggers](https://maritime.sh/docs/triggers), sleep/wake, and the
[SDK](https://maritime.sh/docs/build) if you want to provision one Claude Code agent per customer.

## How it reaches the model

The Claude Agent SDK reads `ANTHROPIC_API_KEY` from the environment and talks to `api.anthropic.com` directly;
agent VMs have normal outbound network access. You bring your own Anthropic key, stored as a secret environment
variable (encrypted at rest, injected only into your agent's VM), and model usage bills to your Anthropic account.
Maritime's [metered LLM proxy](https://maritime.sh/docs/billing#ai-credits) speaks the OpenAI API format, so Claude
Code does not route through it. Pick the model with `CLAUDE_MODEL` (default `claude-opus-5`). The server verifies
the key at boot with a free API call, so a mistyped or revoked key is reported plainly in chat, with the fix, instead
of surfacing as a cryptic failure.

## Keep in mind

- **IS_SANDBOX=1**, as above. The most common failure mode.
- **Build on Linux.** The Agent SDK ships the Claude Code CLI as a platform-specific native package. `npm install`
  must run inside the Docker build; never COPY a host `node_modules` into the image.
- **Bind $PORT.** Maritime injects `PORT=18789`. Hardcode 8080 and the VM boot-loops; that port is already taken
  inside the micro-VM.
- **Exec-form CMD.** Use `CMD ["node", "server.js"]`, not a shell string; shell-form CMDs break under the micro-VM
  init.
- **Respect the 30s reply budget.** Claude Code tasks can run for minutes; the server never cancels them. A long task
  keeps running in the background and its answer arrives as the reply to your next message.
- **Keep Claude Code's state on /data.** Setting `CLAUDE_CONFIG_DIR=/data/.claude` means session transcripts survive
  container recreation, which is what makes cross-restart memory work.

For the general contract this agent implements (any language, any framework), see
[Bring Your Own Framework](https://maritime.sh/docs/frameworks/custom). For the story of building and shipping this
exact agent, read the [blog post](https://maritime.sh/blog/running-claude-code-on-maritime).

---

## Run OpenAI Codex on Maritime
Source: https://maritime.sh/docs/frameworks/codex.md

# Run OpenAI Codex on Maritime

Codex is OpenAI's command-line coding agent: it reads and edits files, runs commands, and works through a task on its
own. Maritime gives it what a laptop session can't: its own always-on micro-VM in the cloud, a persistent workspace,
sleep/wake economics, and every chat channel Maritime supports. The template wraps the
[Codex CLI](https://learn.chatgpt.com/docs/codex/cli) in Maritime's
[bring-your-own-framework contract](https://maritime.sh/docs/frameworks/custom).

> **Note:** **Fastest path:** pick the **Codex** template in the dashboard (or
> `maritime create my-agent --template codex`) and deploy. No key is required: the agent uses Maritime's metered LLM
> access by default. Bring your own OpenAI key or sign in with your ChatGPT plan if you prefer (see below).

## How it fits together

- A small Node server speaks Maritime's contract: `GET /health` and `POST /chat` on `$PORT`.
- Each chat message becomes one `codex exec` run: full Codex with shell and file tools, running unattended inside the
  VM. Approvals and Codex's own sandbox are off because the micro-VM is the sandbox.
- The workspace, Codex's sessions, sign-in and config all live under `/data`, so context survives restarts,
  redeploys, and sleep/wake.
- Each `conversation_id` resumes its own Codex thread: real memory across messages, per conversation.
- The terminal tab runs the interactive `codex` TUI against the same workspace and the same sign-in.

## Three ways to reach the model

The server picks the mode on every message, in this order:

1. **ChatGPT sign-in.** Open the agent's Terminal tab and run `codex login --device-auth`. Codex prints a link and a
   one-time code; finish in your browser. The sign-in is stored at `/data/.codex/auth.json` and survives redeploys.
   It wins over a key when both exist; `codex logout` removes it.
2. **Your own OpenAI key.** Set `OPENAI_API_KEY` in the agent's Settings under Environment variables and restart the
   agent. The key passes through Maritime's proxy untouched and you pay OpenAI directly.
3. **Maritime metered access (default).** With no key set, Maritime injects a per-agent proxy token. Codex talks to
   the proxy over the Responses API and usage is billed to your AI budget per agent. The default model here is
   `gpt-5.5`; set `CODEX_MODEL` to change it in any mode.

Treat `auth.json` like a password: it holds access tokens for your account. It stays on the agent's volume and is
never included in a reply.

## Using the terminal

The template writes `/data/.codex/config.toml` so the interactive TUI reaches the model the same way chat does. The
first line of that file is a marker; while it is there the file is regenerated at boot. Delete the marker line to keep
your own edits.

```bash
# in the agent's Terminal tab
cd /data/workspace
codex                         # interactive Codex, same workspace as chat
codex login --device-auth     # sign in with your ChatGPT plan (optional)
codex login status
```

## Talk to it

```bash
maritime chat my-agent "Clone https://github.com/org/repo into the workspace and run the tests"
maritime chat my-agent "Now fix the failing test and show me the diff"
```

Or use the dashboard chat, the API, or Telegram: every channel lands on the same `POST /chat`. A task that needs
more than a few seconds keeps running in the background; message the agent again and it hands you the finished answer.

## Keep in mind

- Codex runs with `--dangerously-bypass-approvals-and-sandbox`. That is deliberate: nothing outside the VM is
  reachable, and approval prompts would hang a headless run.
- Workspace is `/data/workspace`. Anything written elsewhere can vanish on a redeploy.
- The image pins one Codex CLI version. Newer Codex releases arrive through a new image tag, not through
  `codex update`.
- Want to change the server? The template lives at `backend/templates/codex` in the Maritime repo; deploy your fork
  with [a custom image](https://maritime.sh/docs/frameworks/custom).

---

## DeepSeek Harness Guide
Source: https://maritime.sh/docs/frameworks/deepseek-harness.md

# DeepSeek Harness Guide

DeepSeek Harness (dsh) is DeepSeek's open-source agent harness, and Maritime runs it as a managed, always-on agent
with one command.

## Overview

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) is DeepSeek's open-source agent harness,
released in August 2026. Everything in it is a plugin: models, tools, skills, sessions, sandboxes, and the web
workbench itself. Every run is recorded in append-only session logs you can resume, fork, and replay from the
workbench.

Upstream is an early developer preview that promises breaking changes between releases, so Maritime pins the exact
dsh version in its template image and upgrades deliberately after testing each release.

## Docker Image

Image: `ghcr.io/maritime-sh/dsh-agent:0.1.0-rc.7`

A first-party Maritime image: Node 22, dsh pinned to the tag version, the web workbench on port `3080` behind a
per-agent auth layer, and agent state under `/data/.dsh` so sessions survive restarts and upgrades.

## How It Works

The upstream web workbench ships without authentication, so the Maritime image runs it loopback-only behind a small
auth shim that requires a per-agent token on every request. The Maritime dashboard injects that token for you: click
**Harness Workbench** on the agent page and you are in. The default model routes through the metered Maritime LLM
proxy, so a fresh agent works with no API key at all. Chat messages from Telegram, the CLI, and share links run
one-shot headless turns inside the agent's own container.

```
# The container runs with:
DSH_HEADLESS=true
DSH_PORT=3080
DSH_GATEWAY_TOKEN=<auto-generated>
DSH_MODEL=gpt-5-mini
DSH_HOME=/data/.dsh (baked in the image)
```

## Environment Variables

If you don't supply `OPENAI_API_KEY`, Maritime injects a per-agent proxy token pointed at
`https://api.maritime.sh/api/llm/v1`. Set `DSH_MODEL` to change the default model (any model the proxy serves).
You can also add your own providers, including DeepSeek's API, in the workbench under **Settings > Models**; keys you
add there are stored inside your agent's volume, never on Maritime's control plane.

## Deploy

One command with the [Maritime CLI](https://maritime.sh/docs/cli):

```
maritime create -n my-agent -t dsh && maritime deploy my-agent
```

Or select **Template > DeepSeek Harness** in the Create Agent modal. New here? The
[quickstart](https://maritime.sh/docs/quickstart) covers accounts and the
[Templates guide](https://maritime.sh/docs/templates) covers cloning and sharing agents.

## Talk to it

Open **Harness Workbench** from the agent page for the full experience: sessions, plan mode, tool approvals, session
replay, and plugin management. Or chat from the terminal:

```
maritime chat my-agent "clone my repo and run the tests"
```

Terminal and channel chats are one-shot headless runs: each message boots the harness, runs the task to completion
with tools enabled, and returns the final answer. Recent conversation context carries over between messages;
long-lived interactive sessions live in the workbench.

### Upstream links & resources

- [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness): the source repository (MIT
  license), including the Cordis plugin framework docs.
- [Official dsh documentation](https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart): quickstart,
  provider configuration, CLI profiles, and the plugin development guide.
- [dsh-plugin topic on GitHub](https://github.com/topics/dsh-plugin): community plugins you can install into your
  agent from the Console.

---

## Deploy any container
Source: https://maritime.sh/docs/frameworks/custom.md

# Deploy any container

CrewAI, LangGraph, AutoGen, your own Python script: any Docker image that speaks a three-endpoint contract gets the
whole platform. For a complete worked example of this contract, see
[Run Claude Code on Maritime](https://maritime.sh/docs/frameworks/claude-code); for a plain web app with a public URL
(no chat contract needed), see [Public web agents](https://maritime.sh/docs/web-apps).

## Overview

You do not have to use a Maritime template. Wrap your agent in a small HTTP server, and Maritime gives it everything
the built-in frameworks get: a micro-VM per agent (or per end-user of your product), sleep at ~zero cost with memory
intact, wake on the next message, channels, scheduled wakes, webhooks, and per-agent metering.

## The contract

Three endpoints. That is the whole integration.

```
1. Bind a long-lived server on 0.0.0.0:$PORT   (PORT is injected; never hardcode 8080)
2. GET  /health  ->  any 2xx, fast, no side effects
3. POST /chat    ->  {"message": "...", "source": "front_door" | "cli" | "telegram" | ...}
                 reply within 30s with plain text or {"response": "..."}
```

Accepted reply fields, in priority order: `response`, `reply`, `message`, `text`, `output`. Plain-text bodies
are used verbatim. Slow work should run asynchronously; reply within 30 seconds with what you have.

## CrewAI example

```
# main.py
import os
from fastapi import FastAPI
from crewai import Agent, Crew, Task

app = FastAPI()

researcher = Agent(role="researcher", goal="answer the user well", backstory="…")

@app.get("/health")
def health():
    return {"ok": True}

@app.post("/chat")
async def chat(body: dict):
    task = Task(description=body["message"], expected_output="a helpful answer", agent=researcher)
    result = Crew(agents=[researcher], tasks=[task]).kickoff()
    return {"response": str(result)}
```

```
# Dockerfile
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "start.py"]

# start.py
import os, uvicorn
uvicorn.run("main:app", host="0.0.0.0", port=int(os.getenv("PORT", "8080")))
```

LangGraph, AutoGen, and friends are the same shape: build your graph or group chat once at boot, invoke it inside
`/chat`, return a string.

## The five gotchas

Every one of these has silently broken a real deployment. Check them before anything else.

- **Bind $PORT.** Maritime injects it (currently 18789 inside micro-VMs). Hardcoding 8080 collides with the VM's port
  forwarder and crash-loops the boot.
- **Install ca-certificates.** Slim base images ship without it and every outbound HTTPS call fails with confusing
  TLS errors.
- **Ask for the LLM env vars if you want them.** A custom agent starts with no LLM key, because Maritime does not know
  how your application reads one. Press **Use Maritime LLM** on the agent's Env tab, or send `useMaritimeLlm: true`
  at create. Then `OPENAI_API_KEY` and `OPENAI_BASE_URL` point at Maritime's metered proxy (CrewAI and LangChain
  read both natively). If you bring your own key, set it as a secret env var and do not keep the proxy base URL.
- **Persist to /data only.** It survives restarts, redeploys, and sleep/wake; the rest of the filesystem can vanish on
  a recreate. Your process is snapshotted and resumed, not restarted, so do not trust cached wall-clock time and
  re-establish long-lived connections lazily.
- **No shell-string CMD.** Micro-VM init re-executes your image's CMD as one flattened string, so
  `CMD ["sh", "-c", "uvicorn ... $PORT"]` loses its quoting, the server starts with no arguments, and the VM
  kernel-panics on boot. Launch through a real program (a `start.py` that reads $PORT and calls your server
  directly).

## Deploying

```
# from a GitHub repo with a Dockerfile at the root
maritime create my-brain --repo https://github.com/acme/my-brain

# from a pre-built image on a public registry (framework: "custom", or "crewai"/"langgraph")
curl -X POST https://api.maritime.sh/api/agents \
  -H "Authorization: Bearer $MARITIME_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "my-brain", "framework": "crewai", "imageName": "ghcr.io/acme/support-brain:latest"}'

# swap an existing agent onto a new image or repo build
maritime deploy my-brain --source docker --image ghcr.io/acme/support-brain:v2 --wait
```

Repo and ZIP sources build on Maritime's build worker (see below), so iterate on prompts and configuration through
env vars or files under `/data`, and rebuild the image only when dependencies change. From here the front door
applies unchanged: set the project's `newChatPolicy: "spawn"` and every end-user of your product gets their own
micro-VM running your image.

## How builds work

Repo and ZIP deploys build on a dedicated build machine, never on the host that runs your agent: BuildKit, layer
cache seeded from your previous image, private repos via the Maritime GitHub App, live build logs, loud failures. The
full pipeline, caps, and failure semantics moved to their own page:
[How builds work](https://maritime.sh/docs/builds).

## Scheduled wakes

A sleeping VM's timers do not fire; let Maritime be the alarm clock. Either serve `GET /schedules` returning entries
like the one below (Maritime polls while you are awake and registers real wake triggers), or push the list with one
SDK line (`observeScheduler` / `observe_scheduler`). Maritime wakes the VM about 10 seconds before each occurrence
and delivers `prompt` to `POST /chat` with source `"scheduled"`.

```
{"id": "morning", "cron": "35 9 * * *", "tz": "America/New_York",
 "prompt": "Send the morning summary", "enabled": true}
```

## Checklist

```
[ ] Dockerfile at the repo root (repo/ZIP builds)
[ ] Binds 0.0.0.0:$PORT, not a hardcoded port
[ ] GET /health -> 2xx, fast
[ ] POST /chat -> reply within 30s, {"response": "..."} or plain text
[ ] ca-certificates installed (slim images)
[ ] State lives in /data; process tolerates snapshot/resume
[ ] Scheduled work goes through GET /schedules or the SDK push, never a sleeping-VM timer
```

---

## SDK Reference
Source: https://maritime.sh/docs/sdk.md

# SDK Reference

Complete reference for both Maritime SDKs. New here? Start with the
[Build on Maritime](https://maritime.sh/docs/build) 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](https://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`.

### TypeScript

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

### Python

```python
from maritime import Maritime

client = Maritime(
    api_key="mk_...",                   # or MARITIME_API_KEY
    base_url="https://api.maritime.sh", # or MARITIME_API_URL
    timeout=60.0,                       # per-request seconds
    max_retries=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](https://maritime.sh/docs/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. |

### TypeScript

```typescript
// 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)
```

### Python

```python
# Idempotent per-customer provisioning (recommended)
agent = client.agents.provision(
    external_id=f"customer_{user_id}",
    name=f"assistant-{user_id}",
    template="openclaw",
)

reply = client.agents.chat(agent["id"], "Hello")["response"]
client.agents.set_env(agent["id"], "STRIPE_KEY", "sk_live_...", secret=True)
root = client.agents.files.list(agent["id"])["root"]        # browse / upload / download
client.agents.exec(agent["id"], ["ls", "-la", root])        # one-shot shell command
client.agents.sleep(agent["id"])
client.agents.delete(agent["id"])
```

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

### TypeScript

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

### Python

```python
worker = client.keys.create("chat-worker", scopes=["deploy"])
# worker["raw_key"] is shown once. Store it now.
```

## Webhooks

Receive signed lifecycle events instead of polling. See the
[webhooks guide](https://maritime.sh/docs/sdk/webhooks) 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`.

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

```python
from maritime import MaritimeAPIError

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

### See also

The [Build on Maritime](https://maritime.sh/docs/build) guide (visual walkthrough), the raw
[REST API](https://maritime.sh/docs/api), and the [CLI](https://maritime.sh/docs/cli).

---

## Quickstart
Source: https://maritime.sh/docs/sdk/quickstart.md

# 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

```bash
npm install maritime-sdk
```

### Python

```bash
pip install maritime
```

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](https://maritime.sh/docs/sdk/authentication)).

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

> **Note:** 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.

`when your user signs up`:

### TypeScript

```typescript
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 + '.',
})
```

### Python

```python
from maritime import Maritime

client = Maritime()  # reads MARITIME_API_KEY

agent = client.agents.provision(
    external_id=f"customer_{user.id}",   # your id for this agent
    name=f"assistant-{user.id}",
    template="openclaw",
    instructions=f"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:

*Screenshot: 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

```typescript
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' })
```

### Python

```python
reply = client.agents.chat(agent["id"], "What can you do?")["response"]

# continue a thread:
client.agents.chat(agent["id"], "And after that?", conversation_id="thread-1")
```

## Put it together

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

### Next.js

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

### FastAPI

```python
from fastapi import FastAPI
from maritime import Maritime

app = FastAPI()
client = Maritime()  # reads MARITIME_API_KEY

@app.post("/assistant")
def assistant(user_id: str, message: str):
    agent = client.agents.provision(
        external_id=f"customer_{user_id}",
        name=f"assistant-{user_id}",
        template="openclaw",
    )
    reply = client.agents.chat(agent["id"], message)["response"]
    return {"reply": reply}
```

- [Agents →](https://maritime.sh/docs/sdk/agents): Provision, chat, configure, lifecycle
- [Webhooks →](https://maritime.sh/docs/sdk/webhooks): Get notified on lifecycle events
- [Examples →](https://maritime.sh/docs/sdk/examples): Runnable files on GitHub

---

## Agents
Source: https://maritime.sh/docs/sdk/agents.md

# Agents

Everything you do to a customer's agent (create it, talk to it, configure it, and clean it up) is a method on
`maritime.agents`.

## Provision (get-or-create)

`provision` is idempotent on `externalId`: first call creates the agent, later calls return the same one. That
makes it safe to run on every sign-in: you never double-create, and you never have to store Maritime's agent id. Use
`create` instead if you want a hard failure when the name already exists.

### TypeScript

```typescript
const agent = await maritime.agents.provision({
  externalId: `customer_${user.id}`,
  name: `assistant-${user.id}`,
  template: 'openclaw',              // see /docs/frameworks
  instructions: 'You are a helpful assistant.',
  idleTtlSeconds: 3600,              // 0 = always-on
})
```

### Python

```python
agent = client.agents.provision(
    external_id=f"customer_{user.id}",
    name=f"assistant-{user.id}",
    template="openclaw",              # see /docs/frameworks
    instructions="You are a helpful assistant.",
    idle_ttl_seconds=3600,            # 0 = always-on
)
```

## Chat

Send a message and wait for the reply. Sleeping agents wake automatically. Pass a `conversationId` to keep a
thread. `chat` resolves with `{ response, error? }`. It does **not** throw on a delivery failure (a
still-deploying agent, an LLM error), so check `error`.

### TypeScript

```typescript
const { response, error } = await maritime.agents.chat(agent.id, 'What can you do?')
if (error) throw new Error(error)

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

### Python

```python
result = client.agents.chat(agent["id"], "What can you do?")
if result.get("error"):
    raise RuntimeError(result["error"])
reply = result["response"]

# continue a thread:
client.agents.chat(agent["id"], "And after that?", conversation_id="thread-1")
```

## Per-customer secrets & config

Give each customer's agent its own credentials and config as env vars. Secrets are encrypted at rest; changes reach a
running container after a reload.

### TypeScript

```typescript
await maritime.agents.setEnv(agent.id, 'ACME_API_KEY', user.acmeKey, { secret: true })
await maritime.agents.setEnv(agent.id, 'ACME_REGION', 'us-east', { secret: false })
await maritime.agents.reloadEnv(agent.id)   // push into the running container

// read them back (secret values come back masked):
for (const v of await maritime.agents.listEnv(agent.id)) {
  console.log(v.key, v.isSecret ? '(secret)' : v.value)
}
```

### Python

```python
client.agents.set_env(agent["id"], "ACME_API_KEY", user.acme_key, secret=True)
client.agents.set_env(agent["id"], "ACME_REGION", "us-east", secret=False)
client.agents.reload_env(agent["id"])   # push into the running container

# read them back (secret values come back masked):
for v in client.agents.list_env(agent["id"]):
    print(v["key"], "(secret)" if v.get("isSecret") else v["value"])
```

## Lifecycle, logs & teardown

Agents sleep and wake on their own, but you can drive the lifecycle directly. Find an agent by your own id, read its
logs, or tear it all down when a customer leaves.

### TypeScript

```typescript
const [agent] = await maritime.agents.list({ externalId: `customer_${user.id}` })

await maritime.agents.logs(agent.id, { limit: 100, level: 'error' })

await maritime.agents.sleep(agent.id)     // cheapest resting state
await maritime.agents.start(agent.id)     // wake it
await maritime.agents.restart(agent.id)

await maritime.agents.delete(agent.id)    // container + volume + network
```

### Python

```python
agent = client.agents.list(external_id=f"customer_{user.id}")[0]

client.agents.logs(agent["id"], limit=100, level="error")

client.agents.sleep(agent["id"])     # cheapest resting state
client.agents.start(agent["id"])     # wake it
client.agents.restart(agent["id"])

client.agents.delete(agent["id"])    # container + volume + network
```

## Files & commands

Requires SDK **0.8.0 or later** (`maritime-sdk` on npm, `maritime` on PyPI). On 0.7.x, call the underlying
[REST endpoints](https://maritime.sh/docs/api#files) directly.

`maritime.agents.files` moves bytes both ways and manages the agent's disk; `maritime.agents.exec` runs a one-shot
shell command. Browse and edit operations are scoped to the agent's persistent volume; take its mount from the
`root` that `list` reports rather than hardcoding `/data`. Every call here wakes a sleeping agent; transfers cap
at 100 MB per file. Uploading without `destDir` delivers the file as a chat attachment the agent is told about in
its current conversation.

### TypeScript

```typescript
const { root, entries } = await maritime.agents.files.list(agent.id)

await maritime.agents.files.upload(agent.id, {
  content: csvBytes,
  filename: 'report.csv',
  destDir: `${root}/inbox`,   // omit destDir to deliver as a chat attachment
})

await maritime.agents.files.write(agent.id, `${root}/notes.md`, '# notes')
const bytes = await maritime.agents.files.download(agent.id, `${root}/notes.md`)

await maritime.agents.files.mkdir(agent.id, `${root}/docs`)
await maritime.agents.files.move(agent.id, `${root}/notes.md`, `${root}/docs/notes.md`)
await maritime.agents.files.delete(agent.id, `${root}/docs/notes.md`)

const { exitCode, stdout } = await maritime.agents.exec(agent.id, ['ls', '-la', root])
```

### Python

```python
listing = client.agents.files.list(agent["id"])   # {path, root, entries}
root = listing["root"]

client.agents.files.upload(
    agent["id"], csv_bytes, "report.csv",
    dest_dir=f"{root}/inbox",   # omit dest_dir to deliver as a chat attachment
)

client.agents.files.write(agent["id"], f"{root}/notes.md", "# notes")
data = client.agents.files.download(agent["id"], f"{root}/notes.md")

client.agents.files.mkdir(agent["id"], f"{root}/docs")
client.agents.files.move(agent["id"], f"{root}/notes.md", f"{root}/docs/notes.md")
client.agents.files.delete(agent["id"], f"{root}/docs/notes.md")

result = client.agents.exec(agent["id"], ["ls", "-la", root])
result["exitCode"], result["stdout"]
```

Move raises a conflict (409) when the destination already exists, and move/delete answer 404 for a missing source, so
collisions surface as errors instead of silently doing nothing.

## Scheduled wakes (inside a custom agent)

A sleeping micro-VM's timers never fire, so an agent that must act on a schedule (daily digest, follow-up reminders)
publishes its schedule and lets Maritime be the alarm clock. These helpers run *inside* your agent image, not in your
backend: they read the credentials Maritime injects into every agent and are silent no-ops anywhere else, so they're
safe in local dev. Prefer `nextRunAt` (the next occurrence as your scheduler computed it); an entry with `prompt`
is delivered to your `POST /chat` right after the wake. No SDK? Serve `GET /schedules` returning the same array
and Maritime polls it.

### TypeScript

```typescript
import { observeScheduler, pushSchedules } from 'maritime-sdk'

// One line: every add/remove on your scheduler re-publishes the snapshot.
observeScheduler(myScheduler, {
  getSnapshot: (s) => s.jobs.map(j => ({ id: j.id, nextRunAt: j.next.toISOString() })),
})

// Or push explicitly. Send the FULL list; [] clears all synced wakes.
await pushSchedules([
  { id: 'digest', cron: '0 9 * * 1-5', tz: 'America/New_York', prompt: 'Send the digest' },
  { id: 'followup', nextRunAt: '2026-08-01T14:00:00Z' },
])
```

### Python

```python
from maritime import observe_scheduler, push_schedules

# One line: every add/remove on your scheduler re-publishes the snapshot.
observe_scheduler(
    my_scheduler,
    get_snapshot=lambda s: [
        {"id": j.id, "nextRunAt": j.next_run.isoformat()} for j in s.jobs()
    ],
)

# Or push explicitly. Send the FULL list; [] clears all synced wakes.
push_schedules([
    {"id": "digest", "cron": "0 9 * * 1-5", "tz": "America/New_York",
     "prompt": "Send the digest"},
    {"id": "followup", "nextRunAt": "2026-08-01T14:00:00Z"},
])
```

## Handling errors

Every failure is a typed subclass of `MaritimeError`. Catch the base to catch them all, or narrow by type.

### TypeScript

```typescript
import { MaritimeConflictError, MaritimePaymentRequiredError } from 'maritime-sdk'

try {
  await maritime.agents.create({ name: 'dupe', template: 'openclaw' })
} catch (err) {
  if (err instanceof MaritimeConflictError) {
    // 409: an agent with that name already exists
  } else if (err instanceof MaritimePaymentRequiredError) {
    // 402: plan limit reached, or an add-on needs a paid plan
  } else {
    throw err
  }
}
```

### Python

```python
from maritime import MaritimeConflictError, MaritimePaymentRequiredError

try:
    client.agents.create("dupe", template="openclaw")
except MaritimeConflictError:
    ...  # 409: an agent with that name already exists
except MaritimePaymentRequiredError:
    ...  # 402: plan limit reached, or an add-on needs a paid plan
```

The full error hierarchy (`MaritimeAuthError`, `MaritimeNotFoundError`, `MaritimeRateLimitError`,
`MaritimeConnectionError`) is in the [API reference](https://maritime.sh/docs/sdk).

---

## Webhooks
Source: https://maritime.sh/docs/sdk/webhooks.md

# Webhooks

Get notified when a customer's agent changes state, instead of polling. Subscribe a URL, and Maritime POSTs a signed
JSON body on every lifecycle event.

## Events

Each delivery carries the agent's `external_id`, so you route it to your own customer without a lookup.

| Event | Fires when |
| --- | --- |
| `agent.deployed` | the agent finished deploying and is ready |
| `agent.error` | the agent entered an error state |
| `agent.sleeping` | the agent auto-slept after going idle |
| `agent.woken` | a sleeping agent was woken |
| `agent.restarted` | the agent was restarted |
| `agent.stopped` | the agent was stopped |
| `agent.llm_limit_reached` | the agent reached its monthly AI spend limit |
| `message.reply` | an async API message got its reply |
| `message.failed` | an async API message failed |

## Subscribe

Create a subscription once, from the SDK below or from the dashboard under
[Settings → Webhooks](https://maritime.sh/settings/webhooks). The signing `secret` is returned once. Store it to
verify deliveries. Endpoints must be public `https://` URLs.

### TypeScript

```typescript
const hook = await maritime.webhooks.create({
  url: 'https://your-app.com/maritime/webhook',
  events: ['agent.error', 'agent.deployed'],   // omit for all events
})
// hook.secret is shown once. Store it to verify signatures.
await maritime.webhooks.test(hook.id)          // deliver a synthetic ping
```

### Python

```python
hook = client.webhooks.create(
    url="https://your-app.com/maritime/webhook",
    events=["agent.error", "agent.deployed"],   # omit for all events
)
# hook["secret"] is shown once. Store it to verify signatures.
client.webhooks.test(hook["id"])                # deliver a synthetic ping
```

## Verify the signature

Every delivery is signed. Verify the `X-Maritime-Signature` header (an HMAC-SHA256 of the *raw* body with your
secret) before trusting the payload. **Fail closed** if the secret is unset. Never verify against an empty key.

`your webhook handler`:

```typescript
import crypto from 'node:crypto'

const SECRET = process.env.MARITIME_WEBHOOK_SECRET
if (!SECRET) throw new Error('MARITIME_WEBHOOK_SECRET is required')

export async function POST(req: Request) {
  const raw = await req.text()  // exact bytes: the signature is over these
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(raw).digest('hex')
  if (req.headers.get('x-maritime-signature') !== expected) {
    return new Response('bad signature', { status: 401 })
  }
  const event = JSON.parse(raw)
  // { event: 'agent.error', agent_id, external_id, timestamp, data: {...} }
  console.log(event.event, 'for your customer', event.external_id)
  return new Response('ok')
}
```

> **Note:** Deliveries are best-effort and carry `X-Maritime-Event` and `X-Maritime-Delivery` headers. An
> endpoint that fails repeatedly is auto-disabled; `maritime.webhooks.list()` shows which are disabled, and
> re-enabling happens in the dashboard under Settings → Webhooks.

### Runnable receivers

Full webhook receivers (Express + Flask) that verify the signature are in the
[examples](https://github.com/maritime-sh/maritime-sdk/tree/main/examples).

---

## Authentication & scopes
Source: https://maritime.sh/docs/sdk/authentication.md

# Authentication & scopes

The SDK authenticates with a Maritime API key (`mk_…`). It lives on *your* server and never touches a browser.

## Get a key

Mint one from the dashboard (**Settings → API keys**) or with `maritime keys create`. Set it as
`MARITIME_API_KEY` and both SDKs pick it up automatically.

*Screenshot: A default key is full-access; open Advanced to scope it down.*

## Scopes

Every key carries scopes. Hand a subsystem the *narrowest* key it needs. A leaked key can then only do what its scope
allows. `manage` is a wildcard.

| Scope | Grants |
| --- | --- |
| `provision` | create agents |
| `deploy` | start / stop / restart / sleep / chat |
| `secrets` | read / write env vars |
| `manage` | everything, incl. delete + key management (wildcard) |
| `computers` | the Computers product (MCP and /api/v1/computers); a key with only this scope reaches nothing else, and manage or full access reach Computers too |

## Mint a scoped key

A background worker that only chats to existing agents needs `deploy`, not `provision`, `secrets`, or
`manage`. Minting keys itself requires a `manage` key.

### TypeScript

```typescript
const worker = await maritime.keys.create({
  name: 'chat-worker',
  scopes: ['deploy'],   // chat/start/stop only
})
// worker.rawKey is shown once. Hand it to the worker as MARITIME_API_KEY.
```

### Python

```python
worker = client.keys.create("chat-worker", scopes=["deploy"])
# worker["raw_key"] is shown once. Hand it to the worker as MARITIME_API_KEY.
```

> **Note:** A key sent as a session token (dashboard) and an admin key are always full-access. Scope enforcement
> applies to user `mk_` keys, so restricted keys are genuinely restricted.

---

## Examples
Source: https://maritime.sh/docs/sdk/examples.md

# Examples

Real, runnable files on GitHub. Copy one, set `MARITIME_API_KEY`, and run. Every example is verified to compile
against the published packages.

## Browse the examples

- **Provision on signup**: One agent per customer, idempotent.
  [TypeScript](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/typescript/provision-on-signup.ts),
  [Python](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/python/provision_on_signup.py)
- **Express / FastAPI chat API**: An endpoint that provisions + chats.
  [TypeScript](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/typescript/express-chat-api.ts),
  [Python](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/python/fastapi_app.py)
- **Next.js route handler**: Drop-in app/api/assistant/route.ts.
  [TypeScript](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/typescript/nextjs-route.ts)
- **Webhook receiver**: Verify the HMAC signature, handle events.
  [TypeScript](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/typescript/webhook-receiver.ts),
  [Python](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/python/flask_webhook.py)
- **Scoped worker key**: Mint a deploy-only key for a subsystem.
  [TypeScript](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/typescript/scoped-key.ts),
  [Python](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/python/scoped_key.py)
- **Per-customer secrets**: Set + hot-reload encrypted env vars.
  [TypeScript](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/typescript/manage-secrets.ts),
  [Python](https://github.com/maritime-sh/maritime-sdk/blob/main/examples/python/manage_secrets.py)

The whole set lives in
[github.com/maritime-sh/maritime-sdk/examples](https://github.com/maritime-sh/maritime-sdk/tree/main/examples).

## A note on billing

Agents you provision count against *your* Maritime plan's included agents; extras and add-ons are flat monthly
prices, never metered. See the [billing page](https://maritime.sh/docs/billing). Idle agents auto-sleep, keep their
state, and how much they run never changes the bill.

---

## Migrate to Maritime
Source: https://maritime.sh/docs/migrations.md

# Migrate to Maritime

Move the automation layer of your cloud onto Maritime agents: cron jobs, scheduled functions, background workers, and
bots. Each guide below inventories a provider with read-only credentials, recreates every workload as a Maritime
agent with a schedule and encrypted env vars, verifies it end to end, and only then hands you a reversible cutover
checklist. Hosting is a flat price per agent per month (see
[Billing & plans](https://maritime.sh/docs/billing)), and auto-sleep means a cron agent costs the same whether it
runs for one second or one hour.

> **Note:** **The safety model, in one box.** Inventory runs on read-only credentials you mint for the occasion.
> Credentials travel through env vars, never chat. Nothing on the source provider is modified or deleted by an agent,
> ever: cutover is a checklist you run yourself, and every checklist starts with a reversible step (disable, pause,
> scale to zero) before any delete. Both sides run in parallel until you are satisfied.

Provider guides:

- [AWS](https://maritime.sh/docs/migrations/aws)
- [Google Cloud](https://maritime.sh/docs/migrations/gcp)
- [Azure](https://maritime.sh/docs/migrations/azure)
- [Cloudflare](https://maritime.sh/docs/migrations/cloudflare)
- [Vercel](https://maritime.sh/docs/migrations/vercel)
- [Heroku](https://maritime.sh/docs/migrations/heroku)
- [Fly.io](https://maritime.sh/docs/migrations/fly)
- [Render](https://maritime.sh/docs/migrations/render)
- [DigitalOcean](https://maritime.sh/docs/migrations/digitalocean)
- [VPS / SSH](https://maritime.sh/docs/migrations/vps)

## How every migration works

All ten guides follow the same five steps. They are written to be followed by a coding agent (point Claude Code or
your Maritime agent at one) or by a human in a terminal. Each summary below links to the complete step-by-step
runbook for that provider.

1. **Inventory**: sweep the provider with its own CLI and read-only credentials, and list everything agent-shaped:
   things that wake up, do a job, and go quiet.
2. **Map**: schedule expressions become cron triggers, env vars and secrets become encrypted agent env vars, logs
   become `maritime logs`.
3. **Recreate**: an LLM-driven bot lands on a [framework template](https://maritime.sh/docs/templates); arbitrary
   code lands as a [bring-your-own container](https://maritime.sh/docs/frameworks/custom) from your repo. Porting a
   serverless function into a container is real work, and the guides say so instead of pretending.
4. **Verify**: the new agent must do the job at least once, checked against a known-good run, while the old side is
   still untouched.
5. **Cut over**: disable the old schedule (reversible), watch for a few days, then delete, in that order, with your
   own credentials.

```
npm i -g maritime-cli && maritime login
maritime keys create --name migration --json   # mk_... shown once
export MARITIME_TOKEN=mk_...

maritime templates --json                      # pick a template id from the live list
maritime create nightly-report --template <id> --json
maritime env import nightly-report ./old-provider.env --reload --json
maritime chat nightly-report "run your task once now and report" --json
```

Schedules are recreated as cron triggers on the agent page (see
[Triggers & schedules](https://maritime.sh/docs/triggers)). One gotcha worth knowing up front: timers inside a
sleeping VM do not fire, so scheduled work belongs in a trigger, not in an in-process scheduler, unless the agent is
always-on.

## Migrate from AWS

**What moves:** Scheduled Lambda functions, EventBridge cron rules, ECS scheduled tasks, and bots or workers running
on EC2 instances. Lambda env vars, Secrets Manager entries, and SSM parameters become encrypted agent env vars.

```
# Inventory with a read-only IAM user (ReadOnlyAccess policy)
aws events list-rules --query 'Rules[?ScheduleExpression!=null].[Name,ScheduleExpression,State]' --output table
aws lambda list-functions --query 'Functions[].[FunctionName,Runtime]' --output table
```

EventBridge cron has six fields with ? placeholders; Maritime triggers use standard five-field cron.
cron(0 12 * * ? *) becomes 0 12 * * *, and rate(5 minutes) becomes */5 * * * *.

**What stays:** S3, DynamoDB, RDS, and Route 53 stay on AWS. Your agent keeps calling them with scoped credentials.
VPC-only resources (a private RDS, anything without a public endpoint) are unreachable from Maritime, so flag those
before deciding.

[Read the full AWS runbook →](https://maritime.sh/docs/migrations/aws)

Official docs:
[events list-rules reference](https://docs.aws.amazon.com/cli/latest/reference/events/list-rules.html),
[events delete-rule reference](https://docs.aws.amazon.com/cli/latest/reference/events/delete-rule.html),
[lambda get-function reference](https://docs.aws.amazon.com/cli/latest/reference/lambda/get-function.html),
[Lambda GetFunction API](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunction.html),
[secretsmanager get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html),
[EventBridge schedule expressions](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html),
[Scheduler schedule types and timezones](https://docs.aws.amazon.com/scheduler/latest/UserGuide/schedule-types.html),
[ReadOnlyAccess policy reference](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ReadOnlyAccess.html)

## Migrate from Google Cloud

**What moves:** Cloud Scheduler jobs, scheduled Cloud Functions, Cloud Run jobs, and bots on Compute Engine. Secret
Manager values move into encrypted agent env vars. Cloud Scheduler already uses five-field cron plus a timezone, so
schedules map nearly 1:1.

```
# Inventory with a service account holding roles/viewer
gcloud scheduler jobs list --location=us-central1
gcloud functions list && gcloud run jobs list
```

**What stays:** Cloud Storage, Cloud SQL, BigQuery, Firestore, and Cloud DNS stay. Keep using them from the agent
over public endpoints. A Cloud SQL instance with only a private IP is unreachable from Maritime.

[Read the full Google Cloud runbook →](https://maritime.sh/docs/migrations/gcp)

Official docs:
[gcloud scheduler jobs reference](https://docs.cloud.google.com/sdk/gcloud/reference/scheduler/jobs),
[Cron schedule format](https://docs.cloud.google.com/scheduler/docs/configuring/cron-job-schedules),
[gcloud functions list](https://docs.cloud.google.com/sdk/gcloud/reference/functions/list),
[gcloud run jobs reference](https://docs.cloud.google.com/sdk/gcloud/reference/run/jobs),
[Run jobs on a schedule](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule),
[Secret Manager access control](https://docs.cloud.google.com/secret-manager/docs/access-control),
[Secrets versions access](https://docs.cloud.google.com/sdk/gcloud/reference/secrets/versions/access),
[Service account keys create](https://docs.cloud.google.com/sdk/gcloud/reference/iam/service-accounts/keys/create)

## Migrate from Azure

**What moves:** Azure Functions with timer triggers, Container Apps jobs, Logic Apps automations, and bots on Azure
VMs. Key Vault secrets move into encrypted agent env vars.

```
# Inventory with a service principal holding the Reader role
az functionapp list --output table
az containerapp job list --output table
```

Azure NCRONTAB has six fields including seconds. 0 0 12 * * * becomes 0 12 * * * on a Maritime trigger.

**What stays:** Blob Storage, Azure SQL, Cosmos DB, and Azure DNS stay. Service Bus consumers only move if the
producer can hit a webhook instead, or the agent polls on a schedule. Private endpoints inside a VNet are
unreachable from Maritime.

[Read the full Azure runbook →](https://maritime.sh/docs/migrations/azure)

Official docs:
[az functionapp reference](https://learn.microsoft.com/en-us/cli/azure/functionapp),
[Timer trigger (NCRONTAB)](https://learn.microsoft.com/en-us/azure/azure-functions/functions-bindings-timer),
[Container Apps jobs](https://learn.microsoft.com/en-us/azure/container-apps/jobs),
[az containerapp job reference](https://learn.microsoft.com/en-us/cli/azure/containerapp/job),
[az logic workflow reference](https://learn.microsoft.com/en-us/cli/azure/logic/workflow),
[Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide),
[az ad sp reference](https://learn.microsoft.com/en-us/cli/azure/ad/sp),
[Built-in roles: Reader](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/general)

## Migrate from Cloudflare

**What moves:** Workers on cron triggers, plus their KV and D1 data via export. A Worker that serves HTTP maps to a
public web agent, but Workers runtime bindings (env.KV and friends) must become plain API calls, which is porting
work.

```
# Inventory with a custom read-only API token (never the Global API Key)
npx wrangler deployments list
npx wrangler d1 export my-db --output dump.sql
```

**What stays:** Keep your DNS zones on Cloudflare, along with Pages sites and R2 buckets. R2 is S3-compatible, so the
agent keeps using it directly. Durable Object alarms and Queues are Cloudflare-runtime constructs; moving those is a
rewrite of the trigger model.

[Read the full Cloudflare runbook →](https://maritime.sh/docs/migrations/cloudflare)

Official docs:
[Wrangler Workers commands](https://developers.cloudflare.com/workers/wrangler/commands/workers/),
[Wrangler KV commands](https://developers.cloudflare.com/workers/wrangler/commands/kv/),
[Wrangler v3 to v4 migration](https://developers.cloudflare.com/workers/wrangler/migration/update-v3-to-v4/),
[Cron Triggers](https://developers.cloudflare.com/workers/configuration/cron-triggers/),
[Create a scoped API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/),
[API token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/),
[D1 import and export](https://developers.cloudflare.com/d1/best-practices/import-export-data/),
[R2 S3 API compatibility](https://developers.cloudflare.com/r2/api/s3/api/)

## Migrate from Vercel

**What moves:** Cron jobs from vercel.json and the API routes they hit. The common case is moving only the crons and
background work while the site stays on Vercel. Often the fastest path is recreating the cron logic as instructions
to a framework agent rather than porting the route.

```
# Source of truth is your git repo: read the crons block in vercel.json
vercel project ls
vercel env pull .env.production --environment=production
```

Vercel tokens have no read-only scope, so run the migration locally where you are already logged in, and delete any
token you mint for it afterward.

**What stays:** The Next.js site itself, plus Vercel Postgres, KV, and Blob. Copy connection strings into the agent
env and keep using them. Domains and DNS stay.

[Read the full Vercel runbook →](https://maritime.sh/docs/migrations/vercel)

Official docs:
[Cron Jobs overview](https://vercel.com/docs/cron-jobs),
[Cron usage and pricing](https://vercel.com/docs/cron-jobs/usage-and-pricing),
[vercel.json reference](https://vercel.com/docs/project-configuration/vercel-json),
[vercel env CLI reference](https://vercel.com/docs/cli/env),
[Access tokens](https://vercel.com/docs/accounts/access-tokens),
[vercel project CLI reference](https://vercel.com/docs/cli/project),
[Sensitive environment variables](https://vercel.com/docs/environment-variables/sensitive-environment-variables),
[vercel remove CLI reference](https://vercel.com/docs/cli/remove)

## Migrate from Heroku

**What moves:** Heroku Scheduler jobs, worker and clock dynos, and config vars. Scheduler only offers three
frequencies, so real cron on a Maritime trigger is an upgrade. A worker that only reacts to events can auto-sleep,
which usually costs less than an always-running dyno.

```
heroku apps --json
heroku ps -a my-app
heroku config -a my-app --shell   # write to a local .env, import, delete the file
```

Heroku Scheduler jobs are not listable from the CLI. Open the Scheduler add-on page in the dashboard and copy the
jobs out. Heroku API keys are full-access, so mint a dedicated authorization and revoke it after.

**What stays:** Heroku Postgres and Redis add-ons stay: pull DATABASE_URL and REDIS_URL into the agent env and keep
using them. The web dyno stays if it serves your site.

[Read the full Heroku runbook →](https://maritime.sh/docs/migrations/heroku)

Official docs:
[Heroku Scheduler](https://devcenter.heroku.com/articles/scheduler),
[Procfile](https://devcenter.heroku.com/articles/procfile),
[Config vars](https://devcenter.heroku.com/articles/config-vars),
[OAuth authorizations and scopes](https://devcenter.heroku.com/articles/oauth),
[Dyno types](https://devcenter.heroku.com/articles/dyno-types),
[CLI commands reference](https://devcenter.heroku.com/articles/heroku-cli-commands),
[Postgres credentials and rotation](https://devcenter.heroku.com/articles/heroku-postgresql-credentials),
[Cloning an app with git:clone](https://devcenter.heroku.com/articles/git-clone-heroku-app)

## Migrate from Fly.io

**What moves:** Machines, including scheduled ones, and fly.toml worker processes. Fly apps are already containers
with a Dockerfile, so pointing maritime create at the same repo is nearly direct. Fly schedule granularity (hourly,
daily) upgrades to full cron on Maritime.

```
# Inventory with a read-only org token: fly tokens create readonly
fly apps list
fly machine list -a my-app && fly config show -a my-app
```

fly secrets list shows names and digests only. Secret values are not retrievable by design and must come from your
own records.

**What stays:** Fly Postgres and volumes stay. A database that only listens on the private 6PN network is
unreachable from Maritime, so it needs a public connection option or the workload stays put.

[Read the full Fly.io runbook →](https://maritime.sh/docs/migrations/fly)

Official docs:
[flyctl command reference](https://fly.io/docs/flyctl/),
[Access tokens](https://fly.io/docs/security/tokens/),
[fly machine run and --schedule](https://fly.io/docs/machines/flyctl/fly-machine-run/),
[Task scheduling on Fly](https://fly.io/docs/blueprints/task-scheduling/),
[fly.toml reference](https://fly.io/docs/reference/configuration/),
[Secrets](https://fly.io/docs/apps/secrets/),
[Private networking (6PN)](https://fly.io/docs/networking/private-networking/),
[External Postgres connections](https://fly.io/docs/postgres/connecting/connecting-external/)

## Migrate from Render

**What moves:** Cron job services (a cron expression plus a command, which maps 1:1 to an agent trigger) and
background workers. Env groups and per-service env vars move into encrypted agent env vars.

```
# Source of truth: render.yaml in your repo, or the REST API
curl -s https://api.render.com/v1/services -H "Authorization: Bearer $RENDER_API_KEY"
```

Render API keys are full-account with no read-only scope, so run the migration locally and delete the key from your
Render settings afterward.

**What stays:** Web services and static sites stay if they serve your site. Render Postgres and Key Value stay: use
the external connection string from the agent, since internal-only URLs will not resolve from Maritime.

[Read the full Render runbook →](https://maritime.sh/docs/migrations/render)

Official docs:
[Render cron jobs](https://render.com/docs/cronjobs),
[Background workers](https://render.com/docs/background-workers),
[Blueprint YAML reference](https://render.com/docs/blueprint-spec),
[The Render API](https://render.com/docs/api),
[API: list services](https://api-docs.render.com/reference/list-services),
[API: suspend service](https://api-docs.render.com/reference/suspend-service-1),
[Environment variables and env groups](https://render.com/docs/configure-environment-variables),
[Render Key Value](https://render.com/docs/key-value)

## Migrate from DigitalOcean

**What moves:** App Platform workers and jobs, DO Functions with cron triggers, and bots on droplets (the droplet
interior is the VPS guide below). App spec env values move into encrypted agent env vars.

```
# Inventory with a custom scoped token (read scopes only)
doctl apps list && doctl apps spec get <app-id>
doctl serverless triggers list
```

**What stays:** Spaces buckets are S3-compatible, so keep using them from the agent. Managed databases stay: use the
public connection string and update trusted sources. VPC-only databases are unreachable from Maritime.

[Read the full DigitalOcean runbook →](https://maritime.sh/docs/migrations/digitalocean)

Official docs:
[doctl apps reference](https://docs.digitalocean.com/reference/doctl/reference/apps/),
[App Platform app spec](https://docs.digitalocean.com/products/app-platform/reference/app-spec/),
[Cron and deployment jobs](https://docs.digitalocean.com/products/app-platform/how-to/manage-jobs/),
[Scheduled Functions](https://docs.digitalocean.com/products/functions/how-to/schedule-functions/),
[API token scopes](https://docs.digitalocean.com/reference/api/scopes/),
[doctl droplet-action reference](https://docs.digitalocean.com/reference/doctl/reference/compute/droplet-action/),
[Spaces S3 compatibility](https://docs.digitalocean.com/products/spaces/reference/s3-compatibility/),
[Managed database trusted sources](https://docs.digitalocean.com/products/databases/postgresql/how-to/secure/)

## Migrate from a VPS

**What moves:** The classic case: a $5 box running your bot under tmux. Crontab lines, systemd services and timers,
pm2 and supervisor processes, tmux and screen sessions, and Docker containers all inventory over SSH and land as
agents with triggers.

```
ssh me@box 'crontab -l; systemctl list-timers; pm2 ls; tmux ls; docker ps'
```

There is no enforced read-only SSH, so the guide constrains the agent to an explicit list of read commands and leaves
anything needing sudo to you.

**What stays:** Anything else on the box: a localhost Postgres or Redis, nginx sites, backups. Every localhost
connection string in the env is a decision point, because localhost breaks when the worker moves. Check for other
tenants before canceling the server.

[Read the full a VPS runbook →](https://maritime.sh/docs/migrations/vps)

Official docs:
[crontab(5) reference](https://man7.org/linux/man-pages/man5/crontab.5.html),
[systemd.time calendar syntax](https://man7.org/linux/man-pages/man7/systemd.time.7.html),
[systemd.timer units](https://man7.org/linux/man-pages/man5/systemd.timer.5.html),
[systemctl(1)](https://man7.org/linux/man-pages/man1/systemctl.1.html),
[pm2 process management](https://pm2.keymetrics.io/docs/usage/process-management/),
[supervisorctl](https://supervisord.org/running.html),
[docker inspect reference](https://docs.docker.com/reference/cli/docker/inspect/),
[tmux(1)](https://man7.org/linux/man-pages/man1/tmux.1.html)

### See also

The full flag reference for `maritime create` lives in the
[CLI Reference](https://maritime.sh/docs/cli#maritime-create). Schedules are covered in
[Triggers & schedules](https://maritime.sh/docs/triggers), env vars and sizing in
[Env vars & sizing](https://maritime.sh/docs/configuration). Bringing your own container? Read the
[Deploy any container contract](https://maritime.sh/docs/frameworks/custom) first, especially the CMD rule.

---

## Migrate from AWS to Maritime
Source: https://maritime.sh/docs/migrations/aws.md

# Migrate from AWS to Maritime

Move the automation layer of an AWS account onto Maritime: scheduled Lambda functions, EventBridge cron rules, ECS scheduled tasks, and bots or workers squatting on EC2 instances. Maritime hosts each one as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, credentials stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **Read-only AWS credentials only.** Ask the user to mint a dedicated IAM user or role with the AWS-managed `ReadOnlyAccess` policy. Do not substitute the job-function `ViewOnlyAccess` policy: it is list-only, with no Secrets Manager, no EventBridge Scheduler, and no `lambda:Get*` actions, so half the inventory below fails under it. If the user offers root or admin keys, refuse them and show the read-only setup instead:
   ```bash
   aws iam create-user --user-name maritime-migration-readonly
   aws iam attach-user-policy --user-name maritime-migration-readonly \
     --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess
   aws iam create-access-key --user-name maritime-migration-readonly
   ```
   The human runs those three with their own credentials; you only ever receive the resulting read-only key pair. Remind them to delete this user when the migration is done.
2. **Credentials never travel through chat.** Chat transcripts are logs. Running locally, the user configures a profile themselves (`aws configure --profile maritime-migration`). Running inside a Maritime agent, the user sets `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation.
3. **Never modify or delete anything on AWS.** No `delete-function`, no `disable-rule`, no `terminate-instances`, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template, and the price, and get a yes before each `maritime create`.

## Prerequisites

- `aws` CLI v2, authenticated with the read-only credentials above. Verify with `aws sts get-caller-identity`.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `jq`.

## Step 1: Inventory

Sweep every region the user cares about (`--region` on each call, or loop over `aws ec2 describe-regions`). Collect four kinds of workload:

```bash
# Scheduled EventBridge rules and what they trigger
aws events list-rules --query 'Rules[?ScheduleExpression!=null].[Name,ScheduleExpression,State]' --output table
aws events list-targets-by-rule --rule <rule-name>

# The newer EventBridge Scheduler, if in use. list-schedules omits the expression;
# get-schedule returns ScheduleExpression and ScheduleExpressionTimezone
aws scheduler list-schedules --query 'Schedules[].[Name,GroupName,State]' --output table
aws scheduler get-schedule --name <schedule-name>

# All Lambda functions (cross-reference with rule targets to find the scheduled ones)
aws lambda list-functions --query 'Functions[].[FunctionName,Runtime,Handler,MemorySize]' --output table

# ECS scheduled tasks show up as EventBridge targets with an ecs parameters block; also:
aws ecs list-clusters && aws ecs list-task-definitions

# Long-running bots on EC2
aws ec2 describe-instances --filters Name=instance-state-name,Values=running \
  --query 'Reservations[].Instances[].[InstanceId,Tags[?Key==`Name`].Value|[0],InstanceType]' --output table

# Secrets and parameters the workloads read (names only for now)
aws secretsmanager list-secrets --query 'SecretList[].Name' --output table
aws ssm describe-parameters --query 'Parameters[].Name' --output table
```

Agent-shaped workloads are the ones that wake up, do a job, and go quiet: cron Lambdas, report generators, scrapers, Slack/Telegram bots, queue drainers, sync jobs. Present the inventory to the user as a table (workload, trigger, runtime, what it appears to do) and let them pick what moves.

## Step 2: Map

| AWS concept | Maritime concept |
|---|---|
| Scheduled Lambda / EventBridge cron rule | Agent + trigger (cron schedule) |
| ECS scheduled task | Agent + trigger |
| EC2-hosted bot or worker | Agent (bring-your-own code, always-on or auto-sleep) |
| Lambda env vars, Secrets Manager, SSM params | Agent env vars, AES-encrypted at rest |
| CloudWatch Logs | Agent logs (`maritime logs`) |
| IAM role attached to the workload | Scoped keys in env vars for whatever the agent still calls |

Schedule expressions translate mechanically, with two traps. EventBridge `rate(5 minutes)` becomes `*/5 * * * *`. EventBridge cron has six fields with `?` placeholders; standard cron has five: `cron(0 12 * * ? *)` becomes `0 12 * * *`. Trap one: numeric day-of-week differs. EventBridge counts 1-7 starting at Sunday, standard cron counts 0-6 starting at Sunday, so EventBridge `2-6` (Monday to Friday) becomes `1-5`; convert day names to numbers too, since name ranges are not portable across cron implementations. Trap two: the `L`, `W`, and `#` wildcards have no five-field equivalent; re-derive those schedules by hand. Classic EventBridge rule crons always run in UTC, so keep the trigger timezone UTC unless the user says otherwise. EventBridge Scheduler schedules carry their own `ScheduleExpressionTimezone`; mirror it on the Maritime trigger.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is arbitrary code (a Lambda handler, a container, a script).** This is a port, not a copy, and you should say so. Budget an hour, not a click. Fetch the code read-only:
  ```bash
  aws lambda get-function --function-name <fn> --query 'Code.Location' --output text
  # returns a presigned URL valid for 10 minutes; curl it to get the deployment zip.
  # Container-image functions have no zip: Code shows an ImageUri instead, so
  # source comes from the user's repo or registry.
  ```
  For ECS, `aws ecs describe-task-definition` gives the image ref; the source should come from the user's own repo. Wrap the handler in a small always-running entrypoint or HTTP server, add a Dockerfile, push to a GitHub repo the user controls, then:
  ```bash
  maritime create <name> --repo https://github.com/<user>/<repo> --json
  ```
  Dockerfile gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "python main.py $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly. Install `ca-certificates` in slim images.

**Env vars and secrets.** Pull only the specific secrets the chosen workload reads (this is the one place read scope on secret values is needed):

```bash
aws lambda get-function-configuration --function-name <fn> --query 'Environment.Variables'
aws secretsmanager get-secret-value --secret-id <name> --query 'SecretString' --output text
```

`ReadOnlyAccess` deliberately stops at secret metadata: it does not grant `secretsmanager:GetSecretValue`, so expect `AccessDenied` on that second command. Two clean fixes, both run by the human: attach the AWS-managed `AWSSecretsManagerClientReadOnlyAccess` policy to the migration user for the duration (it adds `GetSecretValue` plus the scoped `kms:Decrypt`), or have the human run the `get-secret-value` calls themselves and put the values straight into the local `.env` file below.

Write them to a local `.env` file, import, then destroy the file:

```bash
maritime env import <agent> ./aws-migration.env --reload --json
rm ./aws-migration.env
```

Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each cron as a Maritime trigger with the converted expression: `maritime triggers create <agent> --type cron --cron "0 12 * * *" --json`, or in the dashboard: agent page, Triggers pane, cron type. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire; either serve `GET /schedules`, use the SDK scheduler observer, or mark the agent `--always-on` at create time.

## Step 4: Verify before touching AWS

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real scheduled firing and check its output against a known-good run from CloudWatch Logs. Both sides can safely run in parallel; that is the point of leaving AWS untouched.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on AWS, so they run them with their own admin credentials. You never run them.

1. Pause the old schedule (reversible): `aws events disable-rule --name <rule>`
2. Watch Maritime for a few days: `maritime logs <agent> --json`. If anything is wrong, `aws events enable-rule --name <rule>` restores AWS in one command.
3. Only when satisfied, delete. A rule with targets refuses to die: first `aws events remove-targets --rule <rule> --ids <target-id>` (ids come from `aws events list-targets-by-rule --rule <rule>`), then `aws events delete-rule --name <rule>` (`--force` is only for rules managed by another AWS service). Then `aws lambda delete-function --function-name <fn>`, terminate the EC2 instance, and remove unused Secrets Manager entries.
4. Delete the migration IAM user made in the safety section: `aws iam delete-access-key --user-name maritime-migration-readonly --access-key-id <id>`, `aws iam detach-user-policy --user-name maritime-migration-readonly --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess` (repeat for `AWSSecretsManagerClientReadOnlyAccess` if it was attached), then `aws iam delete-user --user-name maritime-migration-readonly`.
5. If the migration ran inside a Maritime agent, remove the AWS env vars from it: `maritime env remove <agent> AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.

## What stays on AWS

Be upfront about this list rather than letting the user discover it:

- **S3, DynamoDB, RDS, ElastiCache**: data services do not move. The Maritime agent keeps calling them over the public endpoint with scoped credentials in its env vars. VPC-only resources (an RDS with no public access, anything behind a private subnet) are unreachable from Maritime; flag each one you find and let the user decide (public endpoint with strict security group, a proxy, or leave that workload on AWS).
- **Route 53 / DNS**: stays. Nothing on Maritime needs it unless the user points a domain at a public web agent, which is a separate task.
- **SQS/SNS-driven workloads**: Maritime triggers are cron and webhook shaped. An SQS consumer can move only if the producer can hit a webhook instead, or the agent polls the queue on a schedule. Say which one applies.

## Official AWS documentation

The exact pages behind the claims in this skill, all current as of 2026-08-07:

- [AWS CLI reference: events list-rules](https://docs.aws.amazon.com/cli/latest/reference/events/list-rules.html) (rule fields: Name, ScheduleExpression, State)
- [AWS CLI reference: events delete-rule](https://docs.aws.amazon.com/cli/latest/reference/events/delete-rule.html) (targets must be removed first; what `--force` really does)
- [AWS CLI reference: lambda get-function](https://docs.aws.amazon.com/cli/latest/reference/lambda/get-function.html)
- [Lambda GetFunction API: the presigned Code.Location URL, valid 10 minutes](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunction.html)
- [AWS CLI reference: secretsmanager get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html) (required permissions listed at the top)
- [EventBridge rule schedule expressions: rate and six-field cron, UTC](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html)
- [EventBridge Scheduler schedule types and timezones](https://docs.aws.amazon.com/scheduler/latest/UserGuide/schedule-types.html)
- [ReadOnlyAccess managed policy JSON](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ReadOnlyAccess.html)
- [AWS managed policies for Secrets Manager, including AWSSecretsManagerClientReadOnlyAccess](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_available-policies.html)
- [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)

## Troubleshooting

- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.

Every aws command, flag, and --query expression in this skill was verified on 2026-08-07 against AWS CLI v2.27 offline help and the official documentation linked above, and every maritime command against the CLI source. A live end-to-end run against a real AWS account remains desk-checked only. If a provider-side command errors on a flag, trust `aws <service> <verb> help` over this document and continue.

---

## Migrate from Azure to Maritime
Source: https://maritime.sh/docs/migrations/azure.md

# Migrate from Azure to Maritime

Move the automation layer of an Azure subscription onto Maritime: Azure Functions on timer triggers, Container Apps jobs on a cron schedule, bots or workers squatting on VMs, and Logic Apps running scheduled automations. Maritime hosts each one as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, credentials stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **Read-only Azure credentials only.** Ask the user to mint a dedicated service principal with the built-in `Reader` role at the subscription scope. If the user offers Owner or Contributor credentials, refuse them and show the read-only setup instead:
   ```bash
   az ad sp create-for-rbac --display-name maritime-migration-readonly \
     --role Reader --scopes /subscriptions/<subscription-id>
   # Only if Key Vault secret values must be read (see Step 3):
   az role assignment create --assignee <appId> --role "Key Vault Secrets User" \
     --scope $(az keyvault show --name <vault> --query id -o tsv)
   ```
   The human runs those with their own credentials; you only ever receive the resulting appId, password, and tenant. Remind them to delete this service principal when the migration is done.
2. **Credentials never travel through chat.** Chat transcripts are logs. Running locally, the user signs in themselves (`az login --service-principal -u <appId> -p <password> --tenant <tenant>`). Running inside a Maritime agent, the user sets `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation.
3. **Never modify or delete anything on Azure.** No `az functionapp stop`, no `az vm deallocate`, no `delete` of any kind, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template, and the price, and get a yes before each `maritime create`.

## Prerequisites

- `az` CLI 2.55 or newer, signed in as the read-only service principal above. Verify with `az account show`. The `logic` command group is an extension that az installs automatically on first use (2.55 is its documented minimum, which is where the version floor comes from). The `containerapp` job commands ship in the core CLI on current versions; only older installs need the `containerapp` extension, which also auto-installs.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `jq`.

## Step 1: Inventory

Azure resources are subscription-wide but often spread across resource groups; the list commands below sweep the whole subscription. Collect four kinds of workload:

```bash
# Function apps, then the functions inside each one
az functionapp list --query "[].{name:name, rg:resourceGroup, state:state}" -o table
az functionapp function list -g <rg> -n <app> -o table
az functionapp function show -g <rg> -n <app> --function-name <fn> --query "config.bindings"
# Timer triggers have a binding of type "timerTrigger"; the "schedule" value is NCRONTAB,
# whether it came from function.json or a code attribute. A value like "%MySchedule%"
# resolves through app settings:
az functionapp config appsettings list -g <rg> -n <app> -o table

# Container Apps jobs with a Schedule trigger
az containerapp job list --query "[].{name:name, rg:resourceGroup, trigger:properties.configuration.triggerType, cron:properties.configuration.scheduleTriggerConfig.cronExpression}" -o table

# Long-running bots on VMs
az vm list -d --query "[].{name:name, rg:resourceGroup, power:powerState, size:hardwareProfile.vmSize}" -o table

# Logic Apps doing scheduled automations (Consumption tier; Standard-tier Logic Apps
# run on the Functions runtime and already appear in the functionapp list above)
az logic workflow list --query "[].{name:name, rg:resourceGroup, state:properties.state}" -o table
az logic workflow show -g <rg> -n <wf> --query "properties.definition.triggers"

# Key Vault secrets the workloads read (names only for now)
az keyvault list --query "[].name" -o tsv
az keyvault secret list --vault-name <vault> --query "[].name" -o tsv
```

Agent-shaped workloads are the ones that wake up, do a job, and go quiet: timer functions, report generators, scrapers, Slack/Telegram bots, queue drainers, sync jobs. Present the inventory to the user as a table (workload, trigger, runtime, what it appears to do) and let them pick what moves.

## Step 2: Map

| Azure concept | Maritime concept |
|---|---|
| Function app timer trigger | Agent + trigger (cron schedule) |
| Container Apps scheduled job | Agent + trigger |
| VM-hosted bot or worker | Agent (bring-your-own code, always-on or auto-sleep) |
| Logic App recurrence workflow | Agent + trigger (rebuild connector steps as agent instructions or code) |
| App settings, Key Vault secrets | Agent env vars, AES-encrypted at rest |
| Application Insights / Log Analytics | Agent logs (`maritime logs`) |
| Managed identity on the workload | Scoped keys in env vars for whatever the agent still calls |

Azure Functions timer schedules are NCRONTAB, canonically SIX fields with seconds first: `{second} {minute} {hour} {day} {month} {day-of-week}`. Maritime triggers use standard five-field cron, so drop the leading seconds field when it is `0`: `0 0 12 * * *` becomes `0 12 * * *`, and `0 */5 * * * *` becomes `*/5 * * * *`. Count the fields before converting: NCRONTAB also accepts plain five-field expressions, so a schedule that already has five fields is already standard cron and must be copied unchanged, never stripped. A schedule that actually uses the seconds field (`*/30 * * * * *`, every 30 seconds) fires sub-minute and cannot be expressed in five-field cron; flag it and let the user pick a minutely compromise. NCRONTAB runs in UTC unless the app sets `WEBSITE_TIME_ZONE`, so keep the trigger timezone UTC unless that setting exists. Container Apps job cron expressions are already five fields; copy them verbatim.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is arbitrary code (a function handler, a container, a script).** This is a port, not a copy, and you should say so. Budget an hour, not a click. The Reader role cannot download deployed function code (Kudu zip and publish-profile downloads are write-scoped operations), so the source of truth is the user's own repo; ask for it. For a Container Apps job, `az containerapp job show -g <rg> -n <job> --query "properties.template.containers[].image"` names the image, but the source should still come from the user's repo. Wrap the handler in a small always-running entrypoint or HTTP server, add a Dockerfile, push to a GitHub repo the user controls, then:
  ```bash
  ID=$(maritime create <name> --json | jq -r '.id')
  maritime deploy "$ID" --source github --repo https://github.com/<user>/<repo> --branch main --json
  ```
  Dockerfile gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "python main.py $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly. Install `ca-certificates` in slim images.

**Env vars and secrets.** Function app settings are the workload's env vars; settings whose value looks like `@Microsoft.KeyVault(SecretUri=...)` resolve through Key Vault:

```bash
az functionapp config appsettings list -g <rg> -n <app> -o json
az keyvault secret show --vault-name <vault> --name <secret> --query value -o tsv
```

Reading a secret's value needs the `Key Vault Secrets User` role from the safety section (or a get/list access policy on legacy non-RBAC vaults); the subscription `Reader` role only lists names. Pull only the specific secrets the chosen workload reads.

Write them to a local `.env` file, import, then destroy the file:

```bash
maritime env import <agent> ./azure-migration.env --reload --json
rm ./azure-migration.env
```

Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each cron as a Maritime trigger: dashboard, agent page, Triggers pane, cron type, using the converted expression. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire; either serve `GET /schedules`, use the SDK scheduler observer, or mark the agent `--always-on` at create time.

## Step 4: Verify before touching Azure

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real scheduled firing and check its output against a known-good run from Application Insights or the function's Monitor tab. Both sides can safely run in parallel; that is the point of leaving Azure untouched.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on Azure, so they run them with their own admin credentials. You never run them.

1. Pause the old workload (reversible): `az functionapp stop -g <rg> -n <app>`. For a Logic App: `az logic workflow update -g <rg> -n <wf> --state Disabled`.
2. Watch Maritime for a few days: `maritime logs <agent> --json`. If anything is wrong, `az functionapp start` (or `--state Enabled`) restores Azure in one command.
3. Only when satisfied, delete: `az functionapp delete -g <rg> -n <app>`, `az containerapp job delete -g <rg> -n <job> --yes`, then for VMs `az vm deallocate -g <rg> -n <vm>` followed by `az vm delete -g <rg> -n <vm> --yes`, and remove unused Key Vault secrets.
4. Remove the migration service principal's role assignments, then delete it: `az role assignment delete --assignee <appId>`, then `az ad sp delete --id <appId>`. Deleting the principal alone leaves orphaned assignments that show up later as "Identity not found".
5. If the migration ran inside a Maritime agent, clear `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID` from that agent in the dashboard env vars pane.

## What stays on Azure

Be upfront about this list rather than letting the user discover it:

- **Blob Storage, Azure SQL, Cosmos DB**: data services do not move. The Maritime agent keeps calling them over the public endpoint with scoped credentials (connection strings, SAS tokens) in its env vars. Anything VNet-only, including every private endpoint you find in the inventory, is unreachable from Maritime; flag each one and let the user decide (public endpoint with a strict firewall rule, a proxy, or leave that workload on Azure).
- **Azure DNS**: stays. Nothing on Maritime needs it unless the user points a domain at a public web agent, which is a separate task.
- **Service Bus-driven workloads**: Maritime triggers are cron and webhook shaped. A queue or topic consumer can move only if the producer can hit a webhook instead, or the agent polls on a schedule. Say which one applies.

## Official Azure documentation

The exact pages a migrating user needs, all on learn.microsoft.com:

- [az functionapp command reference](https://learn.microsoft.com/en-us/cli/azure/functionapp) covers `list`, `stop`, `start`, `delete`, and the subgroups used here.
- [Timer trigger for Azure Functions](https://learn.microsoft.com/en-us/azure/azure-functions/functions-bindings-timer) is the NCRONTAB reference: field order, examples, UTC default, and `WEBSITE_TIME_ZONE`.
- [Jobs in Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/jobs) documents trigger types, the five-field UTC cron format, and the `scheduleTriggerConfig` ARM properties.
- [az containerapp job command reference](https://learn.microsoft.com/en-us/cli/azure/containerapp/job) covers `list`, `show`, and `delete`.
- [az logic workflow command reference](https://learn.microsoft.com/en-us/cli/azure/logic/workflow) covers `list`, `show`, and `update --state`, and carries the extension note.
- [az keyvault secret command reference](https://learn.microsoft.com/en-us/cli/azure/keyvault/secret) covers `list` and `show`.
- [Azure RBAC for Key Vault data plane](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) defines Key Vault Secrets User and the RBAC-vs-access-policy permission models.
- [az ad sp command reference](https://learn.microsoft.com/en-us/cli/azure/ad/sp) covers `create-for-rbac` and `delete`.
- [Sign in with a service principal](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli-service-principal) is the `az login --service-principal` reference.
- [Azure built-in roles: General](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/general) is the Reader role definition (`*/read`, control plane only, no data actions).

## Troubleshooting

- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.
- `az` says a `logic` subcommand does not exist: `logic` is an extension that normally auto-installs; `az extension add --name logic` (or `--upgrade`) fixes it. If a `containerapp` subcommand is missing you are on an old CLI; `az extension add --name containerapp` covers it there (current CLI versions have the job commands in core).
- A `--query` path in this skill returns nulls: inspect one resource with the group's `show` command and adapt the path.

Every `az` command, flag, RBAC role claim, and cron-format claim in this skill was verified against the official documentation on learn.microsoft.com on 2026-08-07 (the links above are the pages used). Two things remain desk-checked rather than doc-verified: the exact `--query` paths into command output (the reference pages do not document output shapes; the troubleshooting bullet above covers drift) and the note that Standard-tier Logic Apps appear in the functionapp list. The maritime CLI surface is desk-checked against the current CLI. If a provider-side command errors on a flag, trust `az <group> --help` over this document and continue.

---

## Migrate from Cloudflare to Maritime
Source: https://maritime.sh/docs/migrations/cloudflare.md

# Migrate from Cloudflare to Maritime

Move the automation layer of a Cloudflare account onto Maritime: Workers running on cron triggers, Queues consumers, Durable Object alarms, and the KV, R2, and D1 data behind them. Maritime hosts each one as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, credentials stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **Read-only Cloudflare API token only.** Ask the user to create a custom token at dash.cloudflare.com/profile/api-tokens (Create Token, then Custom Token) with only these permissions: Workers Scripts:Read, Workers KV Storage:Read, D1:Read, Account Settings:Read (add Queues:Read and Workers R2 Storage:Read only if those products are in use). If the user offers their Global API Key, refuse it outright: Global API Keys cannot be scoped and carry full account write access. The human creates the token in their own dashboard; you only ever receive the resulting token. Remind them to delete it when the migration is done. Both wrangler and the REST API read it from the environment:
   ```bash
   export CLOUDFLARE_API_TOKEN=<token>        # the user sets this themselves
   export CLOUDFLARE_ACCOUNT_ID=<account-id>  # shown in the dashboard sidebar
   ```
2. **Credentials never travel through chat.** Chat transcripts are logs. Running locally, the user exports `CLOUDFLARE_API_TOKEN` in their own shell. Running inside a Maritime agent, the user sets `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation.
3. **Never modify or delete anything on Cloudflare.** No `wrangler delete`, no `wrangler deploy`, no trigger edits, no KV or R2 writes, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template, and the price, and get a yes before each `maritime create`.

## Prerequisites

- Node 22+. Current wrangler (4.x) refuses to run on anything older. Run wrangler as `npx wrangler` so you always get the current version; verify auth with `npx wrangler whoami`.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `jq`. If R2 data will actually move (usually it should not, see Step 3), the `aws` CLI or `rclone`.

## Step 1: Inventory

Workers are account-scoped, so no region sweep is needed. Collect the scripts, their cron triggers, and the data stores behind them:

```bash
# Every Worker script in the account
curl -s "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/workers/scripts" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq -r '.result[].id'

# What is actually live for one Worker
npx wrangler deployments list --name <worker>

# Cron triggers. If the source is in git, read the [triggers] crons block in
# wrangler.toml (or wrangler.jsonc). For a deployed-only Worker, ask the API:
curl -s "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/workers/scripts/<worker>/schedules" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq '.result.schedules'

# Data stores the Workers read
npx wrangler kv namespace list
npx wrangler d1 list --json
npx wrangler r2 bucket list
npx wrangler queues list
```

Agent-shaped workloads are the ones that wake up, do a job, and go quiet: cron Workers, report generators, scrapers, webhook bots, sync jobs. While reading source, also record every Queues consumer (`queue()` handler) and Durable Object alarm (`alarm()` handler) you find; they need the rewrite treatment in Step 2. Present the inventory to the user as a table (worker, trigger, bindings, what it appears to do) and let them pick what moves.

**Pulling a Worker whose source is not in git.** Cloudflare's documented recovery path for dashboard-created Workers:

```bash
npx wrangler init --from-dash <worker-name>
```

This is a one-time download: it does not sync later dashboard edits, so treat the result as a snapshot and keep working from git. Expect the Worker script only; do not count on bundled static assets coming down with it. If your wrangler version rejects the flag (some wrangler 3.x builds deprecated it; current wrangler 4.x supports it), the alternative form is `npm create cloudflare@latest <dir> -- --type pre-existing --existing-script <worker-name>`; in general trust `npx wrangler init --help` over this document.

## Step 2: Map

| Cloudflare concept | Maritime concept |
|---|---|
| Worker with cron trigger | Agent + trigger (cron schedule) |
| Worker serving HTTP traffic | Public web agent (code ported to a container server) |
| Queues consumer | Rewrite: webhook trigger or scheduled poll (below) |
| Durable Object alarm | Rewrite: Maritime cron trigger or in-agent scheduler |
| Worker vars and secrets | Agent env vars, AES-encrypted at rest |
| KV namespace | Whatever store the ported code uses (file, Redis, Postgres) |
| R2 bucket | Stays on R2; the agent uses it over the S3 API |
| D1 database | SQLite file on the agent volume, or hosted Postgres |
| `wrangler tail` / dashboard logs | Agent logs (`maritime logs`) |

Schedule expressions copy over verbatim: Cloudflare cron triggers are five-field cron evaluated in UTC, so keep the Maritime trigger timezone UTC unless the user says otherwise. One exception: Cloudflare also accepts non-standard extensions (L, W, and # in the day fields). If a trigger uses them, translate it to plain five-field cron before copying.

**Queues consumers and Durable Object alarms are rewrites; say so plainly.** Both are Cloudflare-runtime constructs with no portable equivalent. A Queues consumer is invoked by the runtime with message batches; on Maritime either the producer changes (it posts to the agent's webhook trigger instead of the queue) or the agent polls the queue on a cron via the Queues pull API (the queue needs an HTTP pull consumer enabled first, and the pulling token needs Queues write scope as well as read, because a pull consumes messages). A Durable Object alarm is a per-object timer; a coarse fixed schedule maps to a Maritime cron trigger, but dynamic per-entity timers mean the ported code needs its own scheduler and almost certainly `--always-on`. Neither case is a migration of the trigger, it is a rewrite of the trigger model. Tell the user which case applies before quoting effort.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is arbitrary Worker code.** This is a port, not a copy, and you should say so. Worker code runs on the Workers runtime, not Node: `env.KV.get()`, `env.DB.prepare()`, the `scheduled()` and `fetch()` handlers, and every binding must be replaced with direct calls (KV REST or a new store, R2 over the S3 API, D1 data via its export) inside a normal long-running process. Wrap it in a small entrypoint or HTTP server, add a Dockerfile, push to a GitHub repo the user controls, then:
  ```bash
  # Cron-shaped Worker: create, then add a Maritime cron trigger (below)
  maritime create <name> --repo https://github.com/<user>/<repo> --json

  # HTTP-serving Worker: it becomes a public web agent, and the code must
  # become a container-run server listening on the port
  maritime create <name> --repo https://github.com/<user>/<repo> --public --port 8080 --json
  ```
  Budget hours, not a click. Dockerfile gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "python main.py $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly. Install `ca-certificates` in slim images.

**Env vars and secrets.** Plain vars are readable from `[vars]` in wrangler.toml or the dashboard settings pane. Worker secret values are write-only on Cloudflare: no API or wrangler command can read them back, so the user must re-supply each secret from wherever it originally came from (password manager, the upstream provider's console). Write everything to a local `.env` file, import, then destroy the file:

```bash
maritime env import <agent> ./cf-migration.env --reload --json
rm ./cf-migration.env
```

Env changes apply on next boot unless you pass `--reload`.

**Data.**

- **KV**: enumerate and bulk-read with the read-only token, then load into whatever store the ported code now uses. Wrangler v4 runs KV data commands against local simulation storage by default, so `--remote` is mandatory here; without it you list an empty local store:
  ```bash
  npx wrangler kv key list --namespace-id=<id> --remote > keys.json
  npx wrangler kv bulk get keys.json --namespace-id=<id> --remote   # open beta; accepts the key-list JSON as-is
  # or per key over REST:
  curl -s "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/storage/kv/namespaces/<ns-id>/values/<key>" \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
  ```
- **R2**: the default is to not move it at all. R2 speaks the S3 API, so the Maritime agent keeps using the bucket directly with a scoped R2 API token in its env vars and endpoint `https://<account-id>.r2.cloudflarestorage.com`. If the user insists on moving the objects: `aws s3 sync s3://<bucket> <dest> --endpoint-url https://<account-id>.r2.cloudflarestorage.com` (the Access Key ID and Secret Access Key shown once at R2 API token creation are the AWS credentials), or rclone.
- **D1**: export the full database, then load the dump into a SQLite file on the agent volume or into a hosted Postgres (expect small SQLite-to-Postgres dialect edits):
  ```bash
  npx wrangler d1 export <db> --remote --output=./dump.sql
  ```

**Schedules.** Recreate each cron as a Maritime trigger: dashboard, agent page, Triggers pane, cron type, expression copied verbatim. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire; either serve `GET /schedules`, use the SDK scheduler observer, or mark the agent `--always-on` at create time.

## Step 4: Verify before touching Cloudflare

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real scheduled firing and check its output against a known-good run from `npx wrangler tail <worker>` or the Workers dashboard logs. Both sides can safely run in parallel; that is the point of leaving Cloudflare untouched.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on Cloudflare, so they run them with their own credentials. You never run them.

1. Pause the old schedule (reversible): remove the `[triggers]` crons block from wrangler.toml and `npx wrangler deploy`. Restoring the block and redeploying restores Cloudflare in one command. For a dashboard-only Worker, remove the cron trigger in the dash under the Worker's Settings, Triggers.
2. Watch Maritime for a few days: `maritime logs <agent> --json`.
3. Only when satisfied, delete the Worker: `npx wrangler delete --name <worker>`. Remove KV namespaces and D1 databases only once nothing else reads them. Do not delete R2 buckets the agent now uses.
4. Delete the migration API token at dash.cloudflare.com/profile/api-tokens.
5. If the migration ran inside a Maritime agent, remove the Cloudflare env vars from it: `maritime env remove <agent> CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`.

## What stays on Cloudflare

Be upfront about this list rather than letting the user discover it:

- **DNS zones**: keep them. Cloudflare DNS is best-in-class and nothing about this migration requires touching it. Pointing a domain at a Maritime public web agent later is one record in the same zone, a separate task.
- **Pages static sites**: stay. Maritime hosts agents, not static sites.
- **R2 buckets**: stay. The agent reaches them over the S3 API with scoped credentials in its env vars; moving object storage is almost never worth it.
- **Turnstile and Zero Trust configuration**: stay. They are account-level products with no Maritime equivalent and no reason to move.
- **Queues**: the queue itself stays as long as anything still produces to it; only the consumer role moves, per the rewrite note in Step 2.

## Official Cloudflare documentation

The exact pages a migrating user needs, each verified current as of 2026-08-07:

- [Wrangler commands reference (index of every command)](https://developers.cloudflare.com/workers/wrangler/commands/)
- [Wrangler Workers commands: init --from-dash, deployments list, tail, delete](https://developers.cloudflare.com/workers/wrangler/commands/workers/)
- [Wrangler KV commands: namespace list, key list, bulk get](https://developers.cloudflare.com/workers/wrangler/commands/kv/)
- [Wrangler v3 to v4 migration guide, including the local-by-default --remote change](https://developers.cloudflare.com/workers/wrangler/migration/update-v3-to-v4/)
- [Cron Triggers: wrangler.toml/wrangler.jsonc syntax, UTC evaluation, extensions](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
- [Create a scoped API token in the dashboard](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
- [API token permission names (Workers Scripts Read, Workers KV Storage Read, D1 Read, and the rest)](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)
- [D1 import and export](https://developers.cloudflare.com/d1/best-practices/import-export-data/)
- [R2 S3 API compatibility and the account endpoint format](https://developers.cloudflare.com/r2/api/s3/api/)
- [Queues pull consumers (HTTP pull, ack, token scopes)](https://developers.cloudflare.com/queues/configuration/pull-consumers/)

## Troubleshooting

- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.
- Cloudflare API answers 403 or `authentication error` (code 10000): the token is missing a read permission. Edit the token at dash.cloudflare.com/profile/api-tokens and add the scope; never fall back to the Global API Key.

Every wrangler command and flag in this skill is verified against live `wrangler 4.120.0` help output, and the REST API paths, token permission names, R2 endpoint format, and cron trigger syntax against official Cloudflare documentation, all on 2026-08-07; the maritime side is checked against the current CLI source. Nothing here was run against a live Cloudflare account, so behavior that only shows up with real credentials remains desk-checked. If a provider-side command errors on a flag, trust `npx wrangler <cmd> --help` over this document and continue.

---

## Migrate from DigitalOcean to Maritime
Source: https://maritime.sh/docs/migrations/digitalocean.md

# Migrate from DigitalOcean to Maritime

Move the automation layer of a DigitalOcean account onto Maritime: App Platform workers and jobs, DO Functions on cron triggers, and bots squatting on droplets. Maritime hosts each one as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, credentials stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **Read-only DigitalOcean token only.** DigitalOcean API tokens support custom scopes with a one-click Read Only preset, so there is no excuse for a full-access token here. Ask the user to mint one at cloud.digitalocean.com/account/api/tokens (Account, API, Tokens tab, Generate New Token) and choose **Read Only**, which grants the `api:read` alias scope, or Custom Scopes with only read scopes checked. If the user offers a legacy full-access token, refuse it and show the scoped flow instead; token scopes cannot be edited after creation, so a fresh token is the only path. The human authenticates it themselves:
   ```bash
   doctl auth init --context maritime-migration   # doctl prompts for the token directly
   doctl account get                              # verify the token works
   ```
   Remind them to revoke this token in the control panel when the migration is done.
2. **Credentials never travel through chat.** Chat transcripts are logs. Running locally, the user runs `doctl auth init` themselves and the token never appears in the conversation. Running inside a Maritime agent, the user sets `DIGITALOCEAN_ACCESS_TOKEN` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation; doctl reads that env var directly.
3. **Never modify or delete anything on DigitalOcean.** No `apps update`, no `apps delete`, no `droplet delete`, no `droplet-action power-off`, no `triggers disable`, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template, and the price, and get a yes before each `maritime create`.

## Prerequisites

- `doctl`, authenticated with the read-only token above. Verify with `doctl account get`.
- For Functions inventory only: `doctl serverless install` once (installs local support), then `doctl serverless connect`. Both work under the read-only token.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `jq`.

## Step 1: Inventory

Three places agent-shaped work hides on DigitalOcean, plus the data layer:

```bash
# App Platform: list apps, then read each spec
doctl apps list
doctl apps spec get <app-id>        # YAML with services, workers, jobs, functions components

# DO Functions and their cron triggers
doctl serverless functions list
doctl serverless triggers list      # columns: Name, Cron, Function, Enabled, LastRun

# Droplets that might host bots
doctl compute droplet list

# Managed databases the workloads read (inventory only, the data stays)
doctl databases list
```

To pull just the agent-shaped components out of a busy app spec:

```bash
doctl apps spec get <app-id> --format json | \
  jq '{workers: [.workers[]?.name], jobs: [.jobs[]? | {name, kind, schedule}], functions: [.functions[]?.name]}'
```

**App Platform now has a native cron component.** A `workers:` entry is a long-running process. A `jobs:` entry is either a deploy-time hook (`kind: PRE_DEPLOY`, `POST_DEPLOY`, or `FAILED_DEPLOY`) or a real cron job: `kind: SCHEDULED` with a `schedule` block holding a five-field `cron` expression and a tz-database `time_zone`, minimum frequency every 15 minutes. Scheduled jobs are a recent addition, so older apps still fake cron with a worker running its own scheduler loop or an external pinger hitting a service endpoint; read the spec first, then the code, so you find both kinds of schedule. One more wrinkle: `functions` components inside an app spec cannot have scheduled triggers at all (DigitalOcean says so outright), so if an in-app function appears to run on a schedule, something external invokes it.

**Droplets: hand off, do not duplicate.** What runs inside a droplet (systemd units, crontabs, pm2, tmux sessions) is exactly the SSH inventory the companion skill `migrate-from-vps` in this folder family already does. Use `doctl compute droplet list` to find candidate droplets and their IPs, then switch to that skill for everything inside the box. This document covers only the droplet's DigitalOcean-side lifecycle (power off, delete) in the cutover list.

Agent-shaped workloads are the ones that wake up, do a job, and go quiet: cron functions, report generators, scrapers, Slack/Telegram bots, queue drainers, sync jobs. Present the inventory to the user as a table (workload, trigger, runtime, what it appears to do) and let them pick what moves.

## Step 2: Map

| DigitalOcean concept | Maritime concept |
|---|---|
| App Platform worker | Agent (always-on or auto-sleep) |
| App Platform job (deploy-time) | Fold into the agent's own startup or deploy; rarely its own agent |
| App Platform scheduled job (`kind: SCHEDULED`) | Agent + trigger (cron schedule) |
| DO Function + cron trigger | Agent + trigger (cron schedule) |
| Worker running a scheduler loop | Agent + trigger, with the loop removed |
| Droplet-hosted bot | Agent via migrate-from-vps |
| App spec `envs`, Functions env | Agent env vars, AES-encrypted at rest |
| App Platform runtime logs, `doctl serverless activations logs` | Agent logs (`maritime logs`) |

DO Functions triggers and App Platform scheduled jobs both use standard five-field cron, so expressions copy to Maritime triggers unchanged. A scheduled job names an explicit tz-database `time_zone`; recreate the Maritime trigger in that timezone. The Functions docs do not commit to a timezone for trigger expressions, so treat those as UTC and verify the first firing time against a known activation. For scheduler-loop workers the schedule lives in code; extract it and recreate it as a real trigger rather than porting the loop. App Platform instance sizes do not carry over: Maritime picks an applicable size at create, and per-agent `--ram`/`--cpu` overrides exist if one workload genuinely needs them.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is arbitrary code (a worker, a job script, a function handler).** App Platform already deploys from the user's git repo, so the source of truth is the repo itself; point Maritime at the same one:
  ```bash
  maritime create <name> --repo https://github.com/<user>/<repo> --json
  ```
  If the component built with a native buildpack (no Dockerfile in the repo), add one. That is porting work, not a click; say so and budget an hour. For DO Functions, fetch the source with `doctl serverless functions get <fn> --code` (this does not work for functions deployed as a zip; take the source from the user's repo instead), wrap the handler in a small always-running entrypoint or HTTP server, and push to a repo the user controls.

  Dockerfile gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "python main.py $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly. Install `ca-certificates` in slim images.

**Env vars and secrets.** Each component's `envs:` block in the app spec carries plain values inline, but anything typed `SECRET` comes back encrypted from `doctl apps spec get`, never as plaintext; DigitalOcean encrypts secret values on first submission and does not return the originals through the API. Those values must come from the user's own records (password manager, original .env file, the upstream service that issued them). Say that plainly up front instead of discovering it at import time. DO Functions env vars ARE retrievable: `doctl serverless functions get <fn> --save-env <file>` (or `-E`) writes them as key=value lines. Route everything into a local `.env` file, import, then destroy the file:

```bash
maritime env import <agent> ./do.env --reload --json
rm ./do.env
```

Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each cron as a Maritime trigger: dashboard, agent page, Triggers pane, cron type, using the expression from `doctl serverless triggers list` or the one extracted from the worker's code. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire; either serve `GET /schedules`, use the SDK scheduler observer, or mark the agent `--always-on` at create time.

## Step 4: Verify before touching DigitalOcean

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real scheduled firing and check its output against a known-good run from App Platform runtime logs or `doctl serverless activations logs --function <fn>`. If the workload writes somewhere observable (a database row, a Slack message, a file in Spaces), check the artifact itself, not just the logs. Both sides can safely run in parallel; that is the point of leaving DigitalOcean untouched.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on DigitalOcean, so they run them with their own credentials. You never run them.

1. Back up every app spec before touching it: `doctl apps spec get <app-id> > backup-<app>.yaml`.
2. Pause, reversibly. App Platform: edit the spec to remove the migrated worker or scheduled-job component and apply with `doctl apps update <app-id> --spec edited.yaml`; applying `backup-<app>.yaml` the same way reverses it. Removing the component is the pause: `instance_count` has a documented minimum of 1, so scaling to zero is not an option. Functions: `doctl serverless triggers disable <trigger>` (enable to reverse). Droplets: `doctl compute droplet-action power-off <droplet-id>` (power-on to reverse), always before any destroy.
3. Watch Maritime for a few days: `maritime logs <agent> --json`.
4. Only when satisfied, delete: `doctl apps delete <app-id>` (or keep the app and apply the trimmed spec permanently), `doctl compute droplet delete <droplet-id>`, and undeploy retired functions with `doctl serverless undeploy <function>`.
5. Revoke the migration token at cloud.digitalocean.com/account/api/tokens.
6. If the migration ran inside a Maritime agent, delete `DIGITALOCEAN_ACCESS_TOKEN` from that agent in the dashboard env vars pane, then `maritime env reload <agent> --json`. The revoked token is dead either way; do not leave it sitting in config.

## What stays on DigitalOcean

Be upfront about this list rather than letting the user discover it:

- **Spaces buckets**: S3-compatible object storage does not move and does not need to. The Maritime agent keeps using the bucket over the S3 API with a scoped Spaces access key pair in its env vars.
- **Managed Databases**: keep them. Put the public connection string (`doctl databases connection <db-id>`) in the agent's env vars and have the user add the agent's traffic to the cluster's trusted sources (Network Access tab). A cluster whose trusted sources admit only VPC-internal resources will refuse Maritime's connections, and the private hostname only resolves inside the VPC; flag each one you find and let the user decide (a trusted-source entry for the agent, a proxy inside the VPC, or leave that workload on DigitalOcean).
- **Load Balancers**: stay, serving whatever web services remain on DigitalOcean.
- **Cloud Firewalls, reserved IPs, VPCs**: droplet plumbing. It retires with the droplets it serves, in the cutover list, not before.
- **DNS hosted at DO**: stays. Nothing on Maritime needs it unless the user points a domain at a public web agent, which is a separate task.

## Official DigitalOcean documentation

The exact pages a migrating user needs, each verified 2026-08-07:

- [doctl apps command reference](https://docs.digitalocean.com/reference/doctl/reference/apps/): every apps subcommand, including list, spec, update, delete, and logs.
- [App spec reference](https://docs.digitalocean.com/products/app-platform/reference/app-spec/): the full YAML schema for services, workers, jobs (all five kinds), functions, and envs.
- [How to manage jobs in App Platform](https://docs.digitalocean.com/products/app-platform/how-to/manage-jobs/): deploy-time versus scheduled (cron) jobs, the SCHEDULED spec template, and the 15-minute floor.
- [How to schedule Functions](https://docs.digitalocean.com/products/functions/how-to/schedule-functions/): scheduled triggers, cron syntax, and project.yml trigger blocks.
- [How to create a personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/): the Read Only preset, custom scopes, and why scopes are immutable after creation.
- [API token scopes reference](https://docs.digitalocean.com/reference/api/scopes/): every scope, including the `api:read` alias the migration token needs.
- [doctl compute droplet-action reference](https://docs.digitalocean.com/reference/doctl/reference/compute/droplet-action/): power-off, power-on, and the rest of the droplet lifecycle verbs used at cutover.
- [Spaces S3 compatibility reference](https://docs.digitalocean.com/products/spaces/reference/s3-compatibility/): which S3 API operations Spaces supports for the agent's continued bucket access.
- [How to secure PostgreSQL managed databases](https://docs.digitalocean.com/products/databases/postgresql/how-to/secure/): trusted sources, the mechanism that must admit the agent's traffic (the MySQL and Valkey pages mirror it).

## Troubleshooting

- `doctl serverless ...` says serverless support is not installed: run `doctl serverless install` once, then `doctl serverless connect`.
- Account has several Functions namespaces: `doctl serverless connect <namespace-hint>` picks one; re-run connect to switch before listing another namespace's functions.
- Secret env vars come back encrypted (not plaintext) from `doctl apps spec get`: expected, not an error. Values come from the user's records.
- `doctl apps spec get` returns the active spec; a deployment in progress can differ. Pass `--deployment <id>` to read a specific deployment's spec.
- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.

The doctl syntax and DigitalOcean platform claims in this skill were verified against official DigitalOcean documentation on 2026-08-07, with one exception: the `doctl serverless triggers` subcommands are missing from the docs site and were verified against the doctl source instead. Nothing here was run against a live DigitalOcean account, and the maritime CLI side remains desk-checked against the current CLI. If a provider-side command errors on a flag, trust `doctl <cmd> --help` over this document and continue.

---

## Migrate from Fly.io to Maritime
Source: https://maritime.sh/docs/migrations/fly.md

# Migrate from Fly.io to Maritime

Move the automation layer of a Fly.io organization onto Maritime: scheduled Machines, worker processes declared in fly.toml, and bots or queue drainers running as ordinary Fly apps. Fly is one of the friendlier sources to migrate from: every Fly app is already a container, so the Dockerfile usually exists in the user's repo and `maritime create <name> --repo <url>` is nearly direct. Maritime hosts each workload as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, credentials stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **Read-only Fly token only.** Ask the user to mint a scoped read-only org token; that is all inventory needs:
   ```bash
   fly tokens create readonly -x 48h
   ```
   The human runs that with their own login; you only ever receive the resulting token. It can read a single org and its resources, nothing else. The `-x 48h` matters: Fly tokens default to a 20 year expiry, and a short-lived token cleans up after itself even if revocation is forgotten. If the user offers the output of `fly auth token` (a full-access personal token) or a deploy token, refuse it and show the readonly command instead. Remind them to revoke the migration token when the migration is done. If the subcommand errors, trust `fly tokens create --help` over this document.
2. **Credentials never travel through chat.** Chat transcripts are logs. Running locally, the user exports `FLY_API_TOKEN` in their own shell. Running inside a Maritime agent, the user sets `FLY_API_TOKEN` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation.
3. **Never modify or delete anything on Fly.** No `fly apps destroy`, no `fly machine stop`, no `fly secrets unset`, no `fly scale`, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target shape (template or repo), and the price, and get a yes before each `maritime create`.

## Prerequisites

- `fly` CLI (flyctl), authenticated with the read-only token above via `FLY_API_TOKEN`. `fly auth whoami` reports the token's identity rather than the human's email when the env var is set; `fly apps list` returning the org's apps is the real smoke test.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `jq`.

## Step 1: Inventory

All of these are read operations, safe under the readonly token:

```bash
# Every app in the organization
fly apps list

# Per app: overall state and the machines behind it
fly status -a <app>
fly machine list -a <app>

# The live app config as deployed (JSON by default; --toml prints fly.toml shape).
# Look at [processes] for worker processes beyond the default web process.
fly config show -a <app>

# Secret NAMES and digests only; values are not retrievable, by design
fly secrets list -a <app>
```

Scheduled Machines are Fly's cron analog: created with `fly machine run <image> --schedule hourly|daily|weekly|monthly`, they show up in `fly machine list` and carry a `schedule` field in the machine config (`fly machine list --json` includes the full config; `fly machine status -d <machine-id> -a <app>` prints one machine's config as JSON if you need to double-check a single machine).

Agent-shaped workloads are the ones that wake up, do a job, and go quiet: scheduled Machines, report generators, scrapers, Slack/Telegram bots, queue drainers, sync jobs, and any `[processes]` worker with no public traffic. Present the inventory to the user as a table (app, process or machine, schedule if any, what it appears to do) and let them pick what moves.

## Step 2: Map

| Fly concept | Maritime concept |
|---|---|
| Fly app (container per Machine) | Agent (bring-your-own code) |
| Scheduled Machine (`--schedule`) | Agent + trigger (cron schedule) |
| fly.toml `[processes]` worker | Its own agent, one per process |
| `fly secrets` | Agent env vars, AES-encrypted at rest |
| `fly logs` | Agent logs (`maritime logs`) |
| Machine auto stop/start | Agent auto-sleep (default) or `--always-on` |

Schedules translate up, not across. Fly offers only four coarse intervals (hourly, daily, weekly, monthly) and fires them on a fuzzy, approximate cycle anchored to the Machine's own runs; the user never chose a wall-clock time. Maritime triggers are real five-field cron, so this is an upgrade: ask the user when the job should actually run instead of transcribing blindly. Mechanical defaults if they have no preference: hourly becomes `0 * * * *`, daily `0 0 * * *`, weekly `0 0 * * 0`, monthly `0 0 1 * *`, all UTC.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is the app's own containerized code, which is the common Fly case.** The repo already has a Dockerfile because Fly deployed from one (hand-written or generated by `fly launch`), so this is close to a direct move:
  ```bash
  maritime create <name> --repo https://github.com/<user>/<repo> --json
  ```
  Before deploying, READ the Dockerfile. Two things bite:
  - Never a shell-string CMD like `CMD ["sh", "-c", "python main.py $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly, exec form. Fly's builder tolerates shell-string CMDs, so a long-deployed Fly app proves nothing here; check anyway.
  - Install `ca-certificates` in slim images.

  fly.toml `[processes]` command overrides do not travel with the Dockerfile. Give each worker process its own agent, and make its Dockerfile CMD (in a branch or a small dedicated repo) launch that process's command directly.

  If only an image remains because the source repo is lost, `fly image show -a <app>` names the deployed image ref, but prefer recovering the source: `registry.fly.io` images need Fly credentials to pull, and rebuilding from source keeps the agent reproducible.

**Sizing and sleep.** Fly Machines auto stop and start; Maritime's default is the same shape, agents auto-sleep when idle and wake on demand, so most workloads need no sizing flags at all. If a Fly Machine was pinned to a specific VM size (`fly machine list` shows each machine's size), mirror it with the optional create-time overrides:

```bash
maritime create <name> --repo <url> \
  --ram 2048 \        # MB, mirror the Fly Machine memory
  --cpu 1 \           # vCPU cores
  --idle 600 \        # sleep 600s after the last request
  --json
```

Use `--always-on` instead of `--idle` for bots that hold a persistent connection (Telegram, Discord, long-lived queue consumers); scheduled and polling jobs should keep the default auto-sleep. Resources apply at provision time; changing `--ram`/`--cpu`/`--disk` later needs a recreate, while idle settings update live.

**Env vars and secrets.** Say this plainly to the user up front: `fly secrets list` shows names and digests only, and secret values are not retrievable through the secrets API by design; only the running app ever sees them. The values must come from the user's own records: a password manager, local `.env` files, or the dashboards of the upstream services the secrets belong to. One more honest source: since the running app sees its secrets as plain env vars, the human, with their own full-access login, can read them off a live Machine with `fly ssh console -a <app>` and `env`. That is their command to run, never yours, and the readonly token cannot do it. Do not suggest `fly console` for this; it boots a new billable Machine instead of entering the existing one. Build the list of required names from `fly secrets list` and `fly config show` (the `[env]` section holds the non-secret vars), then have the user assemble a local file themselves:

```bash
# The user fills fly.env from their own records, one KEY=value per line.
maritime env import <agent> ./fly.env --reload --json
rm ./fly.env
```

If a value is genuinely unrecoverable, rotate it at the upstream service and use the new value; that is normal and safer than archaeology. Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each scheduled Machine as a Maritime trigger: dashboard, agent page, Triggers pane, cron type, using the expression agreed in Step 2. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire; either serve `GET /schedules`, use the SDK scheduler observer, or mark the agent `--always-on` at create time.

## Step 4: Verify before touching Fly

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real trigger firing and compare its output against a known-good run from `fly logs -a <app>`. For auto-sleep agents, also confirm the job survives a sleep/wake cycle: let the agent go idle, then trigger it again and check the logs. Both sides can safely run in parallel; that is the point of leaving Fly untouched.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on Fly, so they run them with their own full-access login. You never run them.

1. Pause the old app (reversible): `fly machine stop <machine-id> -a <app>` for each Machine, reversed with `fly machine start <machine-id> -a <app>`. Stopping keeps the Machines and their config in place, which is exactly what a trial cutover wants. `fly scale count 0 -a <app>` also pauses the app (name every process on a multi-process app: `fly scale count web=0 worker=0`), but know what it does: scaling down destroys the Machines, and restoring means recreating them with `fly scale count web=1` (add `-g <process>` variants as needed) or a fresh `fly deploy`. Prefer stop/start for the trial window.
2. Watch Maritime for a few days: `maritime logs <agent> --json`. If anything is wrong, scale Fly back up and keep both running.
3. Only when satisfied, retire the app: `fly apps destroy <app>`. This permanently removes its Machines, volumes, and IPs, so export any volume data first (see below).
4. Revoke the migration token: `fly tokens list --scope org` (the readonly token is org-scoped; the list defaults to app scope), then `fly tokens revoke <token-id>`. If those subcommands have drifted, trust `fly tokens --help` over this document.
5. If the migration ran inside a Maritime agent, remove `FLY_API_TOKEN` from that agent via the dashboard env vars pane.

## What stays on Fly

Be upfront about this list rather than letting the user discover it:

- **Fly Postgres and anything else on the private network.** Data does not move, and reachability is the hard part. `fly proxy` is a WireGuard tunnel on the user's local machine, so a Maritime agent cannot use it. If the database is reachable only over Fly's private 6PN network, the agent cannot connect at all. The honest options: enable Fly's public connection path for that Postgres (external port on a dedicated IP), move the database to a managed provider, or leave that workload on Fly. A private-network-only database is a genuine blocker to weigh, not a footnote.
- **Volumes and LiteFS.** Fly volume data does not migrate; the human exports anything they need before step 3 above deletes it (app deletion removes the volumes and their snapshots together). LiteFS-replicated SQLite is Fly-specific, so an app built around it keeps its data plan on Fly or redesigns storage first.
- **Anycast IPs, certificates, custom domains.** These stay with Fly. If a public web agent on Maritime replaces the app, re-pointing DNS is a separate task after the migration, not part of it.

## Official Fly.io documentation

The exact pages a migrating user needs, verified current as of 2026-08-07:

- [flyctl command reference](https://fly.io/docs/flyctl/): index of every fly command used in this skill.
- [Access tokens](https://fly.io/docs/security/tokens/): token varieties, what the read-only org token can and cannot do, listing and revoking.
- [fly tokens create readonly](https://fly.io/docs/flyctl/tokens-create-readonly/): the one command the human runs for you, including the `-x` expiry flag and the 20 year default.
- [Run a new Machine](https://fly.io/docs/machines/flyctl/fly-machine-run/): `fly machine run`, including the `--schedule` flag and its fuzzy hourly/daily/weekly/monthly cycle.
- [Task scheduling on Fly](https://fly.io/docs/blueprints/task-scheduling/): Fly's own comparison of scheduled Machines against cron alternatives, and why interval buckets are the only granularity.
- [fly.toml reference](https://fly.io/docs/reference/configuration/): the `[processes]` section that defines worker process groups and the `[env]` section holding non-secret vars.
- [Secrets](https://fly.io/docs/apps/secrets/): how secrets reach the app as env vars and why plain-text read-back is not allowed.
- [Private networking](https://fly.io/docs/networking/private-networking/): 6PN, `.internal` addresses, and why nothing outside the org's WireGuard mesh can reach them.
- [Connect to Postgres from outside Fly](https://fly.io/docs/postgres/connecting/connecting-external/): the dedicated-IP-plus-external-port recipe referenced under "What stays on Fly".
- [Delete an app](https://fly.io/docs/apps/delete/): confirms `fly apps destroy` removes Machines, volumes, snapshots, and IPs, and to export data first.

## Troubleshooting

- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.
- A secret nobody can find the value for: the secrets API never returns values, and if no Machine is still running there is nothing for the human to read it from. Rotate it at the upstream service and import the new value.
- A `fly` read command returns 403 under the readonly token: some subcommands want broader scope. Have the human run that single read with their own login and paste the output; do not upgrade the migration token.

Every fly command and flag in this skill was verified against the official Fly.io documentation linked above on 2026-08-07, and the maritime commands against the current maritime CLI source; flyctl itself was not run live during that pass. If a provider-side command errors on a flag, trust `fly <cmd> --help` over this document and continue.

---

## Migrate from Google Cloud to Maritime
Source: https://maritime.sh/docs/migrations/gcp.md

# Migrate from Google Cloud to Maritime

Move the automation layer of a GCP project onto Maritime: Cloud Scheduler cron jobs, scheduled Cloud Functions (gen1 and gen2), Cloud Run jobs, Cloud Run services acting as workers, and bots or workers squatting on Compute Engine instances. Maritime hosts each one as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, credentials stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **Read-only GCP credentials only.** Ask the user to mint a dedicated service account with `roles/viewer`. If the user offers an owner or editor key, refuse it and show the read-only setup instead:
   ```bash
   gcloud iam service-accounts create maritime-migration-readonly \
     --display-name="Maritime migration (read-only)"
   gcloud projects add-iam-policy-binding <PROJECT_ID> \
     --member="serviceAccount:maritime-migration-readonly@<PROJECT_ID>.iam.gserviceaccount.com" \
     --role="roles/viewer"
   gcloud iam service-accounts keys create maritime-migration-key.json \
     --iam-account=maritime-migration-readonly@<PROJECT_ID>.iam.gserviceaccount.com
   ```
   The human runs those three with their own credentials; you only ever receive the resulting key file. `roles/viewer` lists secrets but cannot read their values; when step 3 needs a value, the human additionally grants `roles/secretmanager.secretAccessor` on just the secrets the chosen workload reads:
   ```bash
   gcloud secrets add-iam-policy-binding <secret-name> \
     --member="serviceAccount:maritime-migration-readonly@<PROJECT_ID>.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
   ```
   Remind them to delete this service account when the migration is done.
2. **Credentials never travel through chat.** Chat transcripts are logs. Running locally, the user activates the key themselves (`gcloud auth activate-service-account --key-file=maritime-migration-key.json`). Running inside a Maritime agent, the user sets `GCP_SA_KEY` (the key file contents) and `GCP_PROJECT_ID` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation; the agent writes the key to a file and activates it the same way.
3. **Never modify or delete anything on GCP.** No `functions delete`, no `scheduler jobs pause`, no `instances stop`, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template, and the price, and get a yes before each `maritime create`.

## Prerequisites

- `gcloud` CLI, authenticated as the read-only service account above, with the project set (`gcloud config set project <PROJECT_ID>`). Verify with `gcloud auth list`.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `jq`.

## Step 1: Inventory

Sweep every project the user cares about (`gcloud projects list`, then `gcloud config set project` per pass). Collect four kinds of workload:

```bash
# Cloud Scheduler cron jobs (regional; loop over locations)
gcloud scheduler locations list --format="value(locationId)"
gcloud scheduler jobs list --location=<loc>
gcloud scheduler jobs describe <job> --location=<loc>   # schedule, timeZone, target

# Cloud Functions, gen1 and gen2 (the ENVIRONMENT column tells them apart;
# older gcloud versions lack it, so rerun as `gcloud functions list --v2`,
# which returns both generations in v2 format with an `environment` field)
gcloud functions list

# Cloud Run jobs, and services acting as background workers
gcloud run jobs list
gcloud run services list

# Long-running bots on Compute Engine
gcloud compute instances list --filter="status=RUNNING"

# Secrets the workloads read (names only for now; list never returns secret data)
gcloud secrets list
```

Cross-reference each Scheduler job's target (an HTTP URL, a Pub/Sub topic, a Cloud Run jobs `:run` call against `run.googleapis.com`, or on legacy cron.yaml jobs an App Engine handler) against the function and Run lists to find which ones are actually scheduled. Agent-shaped workloads are the ones that wake up, do a job, and go quiet: cron functions, report generators, scrapers, Slack/Telegram bots, queue drainers, sync jobs. Present the inventory to the user as a table (workload, trigger, runtime, what it appears to do) and let them pick what moves.

## Step 2: Map

| GCP concept | Maritime concept |
|---|---|
| Cloud Scheduler job | Agent + trigger (cron schedule) |
| Scheduled Cloud Function (gen1 or gen2) | Agent + trigger |
| Cloud Run job | Agent + trigger |
| GCE-hosted bot or worker | Agent (bring-your-own code, always-on or auto-sleep) |
| Function/Run env vars, Secret Manager | Agent env vars, AES-encrypted at rest |
| Cloud Logging | Agent logs (`maritime logs`) |
| Service account attached to the workload | Scoped keys in env vars for whatever the agent still calls |

Schedule conversion is nearly 1:1. Cloud Scheduler already speaks five-field unix-cron, with the timezone stored separately in the job's `timeZone` field: copy the `schedule` expression as-is and set the Maritime trigger's timezone to the job's `timeZone`. The one thing to watch is legacy App Engine syntax (`every 5 minutes`) on old jobs; rewrite those as standard cron (`*/5 * * * *`).

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is arbitrary code (a function, a container, a script).** This is a port, not a copy, and you should say so. Budget an hour, not a click. The source should come from the user's own repo; failing that, the deployed artifact is readable:
  ```bash
  gcloud functions describe <fn> --region=<region> --format=json
  # gen1: sourceArchiveUrl is a gs:// path; gen2: buildConfig.source.storageSource
  gcloud storage cp gs://<bucket>/<object> ./source.zip
  gcloud run jobs describe <job> --region=<region> --format=json   # container image ref
  ```
  If the `cp` returns 403, that is expected: basic `roles/viewer` carries no `storage.objects.get`, so it can see the archive's path but not download it. The human grants the migration service account `roles/storage.objectViewer` on that one source bucket (still read-only), or downloads the file themselves.

  Wrap the entrypoint in a small always-running program or HTTP server, add a Dockerfile, push to a GitHub repo the user controls, then:
  ```bash
  ID=$(maritime create <name> --json | jq -r '.id')
  maritime deploy "$ID" --source github --repo https://github.com/<user>/<repo> --branch main --json
  ```
  Dockerfile gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "python main.py $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly. Install `ca-certificates` in slim images.

**Env vars and secrets.** Pull only the specific secrets the chosen workload reads (this is the one place the `secretAccessor` grant from the safety section is needed):

```bash
gcloud functions describe <fn> --region=<region> --format=json
# env vars live at environmentVariables (gen1) or serviceConfig.environmentVariables (gen2)
gcloud secrets versions access latest --secret=<name>
```

Write them to a local `.env` file, import, then destroy the file:

```bash
maritime env import <agent> ./gcp-migration.env --reload --json
rm ./gcp-migration.env
```

Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each cron as a Maritime trigger: dashboard, agent page, Triggers pane, cron type, using the copied expression and the job's timezone. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire; either serve `GET /schedules`, use the SDK scheduler observer, or mark the agent `--always-on` at create time.

## Step 4: Verify before touching GCP

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real scheduled firing and check its output against a known-good run from Cloud Logging. Both sides can safely run in parallel; that is the point of leaving GCP untouched.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on GCP, so they run them with their own admin credentials. You never run them.

1. Pause the old schedule (genuinely reversible): `gcloud scheduler jobs pause <job> --location=<loc>`
2. Watch Maritime for a few days: `maritime logs <agent> --json`. If anything is wrong, `gcloud scheduler jobs resume <job> --location=<loc>` restores GCP in one command.
3. Only when satisfied, delete: `gcloud scheduler jobs delete <job> --location=<loc>`, `gcloud functions delete <fn> --region=<region>`, `gcloud run jobs delete <job> --region=<region>`, delete the GCE instance, and remove unused Secret Manager entries.
4. Delete the migration service account made in the safety section: `gcloud projects remove-iam-policy-binding <PROJECT_ID> --member="serviceAccount:maritime-migration-readonly@<PROJECT_ID>.iam.gserviceaccount.com" --role="roles/viewer"`, the same per-secret `remove-iam-policy-binding` for any `secretAccessor` grants, then `gcloud iam service-accounts delete maritime-migration-readonly@<PROJECT_ID>.iam.gserviceaccount.com` (deleting the account kills its keys).
5. If the migration ran inside a Maritime agent, remove `GCP_SA_KEY` and `GCP_PROJECT_ID` from its dashboard env vars pane and delete the key file the agent wrote to disk.

## What stays on Google Cloud

Be upfront about this list rather than letting the user discover it:

- **GCS, Cloud SQL, BigQuery, Firestore**: data services do not move. The Maritime agent keeps calling them over the public endpoint with scoped credentials in its env vars. VPC-only resources are unreachable from Maritime: a Cloud SQL instance with only a private IP is the classic case; flag each one you find and let the user decide (public IP with strict authorized networks, a proxy, or leave that workload on GCP).
- **Cloud DNS**: stays. Nothing on Maritime needs it unless the user points a domain at a public web agent, which is a separate task.
- **Pub/Sub-driven workloads**: Maritime triggers are cron and webhook shaped. A Pub/Sub subscriber can move only if the topic can gain a push subscription aimed at a webhook, or the agent polls the subscription on a schedule. Say which one applies.

## Official Google Cloud documentation

The exact pages a migrating user needs, in the order this skill uses them:

- [gcloud scheduler jobs reference (list, describe, pause, resume, delete)](https://docs.cloud.google.com/sdk/gcloud/reference/scheduler/jobs)
- [Cloud Scheduler cron schedule format (five-field unix-cron, time zones, legacy cron.yaml)](https://docs.cloud.google.com/scheduler/docs/configuring/cron-job-schedules)
- [gcloud functions list (gen1 via v1 API, gen2 via v2 API, --v2 flag)](https://docs.cloud.google.com/sdk/gcloud/reference/functions/list)
- [gcloud functions describe (per-generation output format, --region)](https://docs.cloud.google.com/sdk/gcloud/reference/functions/describe)
- [gcloud run jobs reference (list, describe, delete, --region)](https://docs.cloud.google.com/sdk/gcloud/reference/run/jobs)
- [Execute Cloud Run jobs on a schedule (the Scheduler :run HTTP target)](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule)
- [Secret Manager access control (why roles/viewer cannot read secret values)](https://docs.cloud.google.com/secret-manager/docs/access-control)
- [gcloud secrets versions access (latest alias, --secret, --out-file)](https://docs.cloud.google.com/sdk/gcloud/reference/secrets/versions/access)
- [gcloud iam service-accounts keys create (key file for the read-only account)](https://docs.cloud.google.com/sdk/gcloud/reference/iam/service-accounts/keys/create)
- [gcloud storage cp (downloading a function's source archive)](https://docs.cloud.google.com/sdk/gcloud/reference/storage/cp)

## Troubleshooting

- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.

Every gcloud command, flag, role claim, and field path in this skill was verified against the official Google Cloud documentation linked above on 2026-08-07, and every maritime command against the current maritime CLI; the gcloud commands were not executed live from this machine, and cosmetic details of table output (column names such as ENVIRONMENT) remain desk-checked. If a provider-side command errors on a flag, trust `gcloud <group> --help` over this document and continue.

---

## Migrate from Heroku to Maritime
Source: https://maritime.sh/docs/migrations/heroku.md

# Migrate from Heroku to Maritime

Move the automation layer of a Heroku account onto Maritime: worker dynos, Heroku Scheduler jobs, and clock processes. These are exactly agent-shaped, a process that wakes up, does a job, and goes quiet, so Heroku is one of the best-fit sources. Maritime hosts each one as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent. The common outcome: the web dyno stays on Heroku serving the site, and only the workers and schedulers move.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, credentials stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **Mint a read-only, expiring token; never hand over a full-access credential.** Heroku's default credentials are full-access: the CLI login token and the account API key carry the `global` scope. But OAuth authorizations accept scopes, and `read-protected` is read-only while still covering config vars, which the env export in Step 3 needs (plain `read` excludes config vars). The honest posture is still: prefer running locally where the user is already `heroku login`-ed and no credential ever moves. If the migration must run inside a Maritime agent, the human mints a scoped, expiring token on their own machine and revokes it the moment the migration ends:
   ```bash
   heroku authorizations:create -d maritime-migration -s read-protected -e 86400   # human runs; note the Id and Token
   # ...after the migration:
   heroku authorizations:revoke <id>
   ```
   `-e` is seconds, so this token dies on its own after a day; revoke it anyway. Two caveats: account-scope commands fail under it (`heroku auth:whoami` reads account info, which the scope excludes), so sanity-check the token with `heroku apps` instead; and the scope is Heroku's server-side backstop, not a license to try writes, so rule 3 below is still absolute.
2. **Credentials never travel through chat.** Chat transcripts are logs. Locally, the Heroku CLI holds its own auth. Inside a Maritime agent, the user sets `HEROKU_API_KEY` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation.
3. **Never run a mutating heroku command.** No `ps:scale`, no `config:set`, no `addons:destroy`, no `apps:destroy`, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template, and the price, and get a yes before each `maritime create`.

## Prerequisites

- `heroku` CLI, logged in. Verify with `heroku auth:whoami`. Inside a Maritime agent, `HEROKU_API_KEY` holds the scoped token from the safety section instead, and the sanity check is `heroku apps` (whoami fails by design under a scoped token).
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `jq`.

## Step 1: Inventory

Three read-only sweeps, plus one honest ask.

```bash
# Every app on the account
heroku apps --json | jq -r '.[].name'

# Dyno formation per app: worker and clock lines are the targets, web usually stays
heroku ps -a <app>

# Add-ons: look for scheduler, heroku-postgresql, heroku-redis
heroku addons -a <app>

# Recent releases help spot dead apps not worth migrating
heroku releases -a <app>
```

**Procfile.** The repo's Procfile names the process types. `web:` serves HTTP and usually stays on Heroku. `worker:` and `clock:` lines are the agent-shaped workloads; record each one's exact command.

**Heroku Scheduler, the honest part.** Scheduler jobs cannot be listed from the CLI; there is no command for it. Ask the user to open `https://dashboard.heroku.com/apps/<app>/scheduler` (or run `heroku addons:open scheduler -a <app>`) and read each job back: the command, the frequency (every 10 minutes, hourly, or daily), and the UTC time. That dictated list is the inventory; write it down verbatim.

**Clock processes.** A `clock:` dyno keeps its schedules in code, not in Heroku. Grep the repo for the scheduler library (APScheduler, `whenever`, node-cron, celery beat) and extract each schedule expression. Each one becomes its own Maritime trigger.

Present the inventory to the user as a table (app, process or job, schedule, what it appears to do) and let them pick what moves.

## Step 2: Map

| Heroku concept | Maritime concept |
|---|---|
| Worker dyno (`worker:` in Procfile) | Agent, likely `--always-on` |
| Heroku Scheduler job | Agent + cron trigger, auto-sleep |
| Clock process (in-code schedules) | Agent + one trigger per schedule |
| Config vars | Agent env vars, AES-encrypted at rest |
| `heroku logs` | Agent logs (`maritime logs`) |
| Heroku Postgres / Redis add-ons | Stay on Heroku; the agent connects over the public URL |

**Schedules convert upward.** Heroku Scheduler supports only three shapes, all at fixed UTC times, so the mapping to real cron is mechanical and strictly an upgrade:

| Heroku Scheduler setting | Maritime cron |
|---|---|
| Every 10 minutes | `*/10 * * * *` |
| Hourly at :30 | `30 * * * *` |
| Daily at 05:00 UTC | `0 5 * * *` |

Keep the trigger timezone UTC so behavior matches on day one. Then, if the user wants, express what Scheduler never could: weekday-only runs, every 5 minutes, monthly reports.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is arbitrary code (most worker dynos and Scheduler jobs).** This is a port, not a copy, and you should say so. The code is usually already in the user's own git repo, since that is how it reached Heroku. If the only copy lives on Heroku:
  ```bash
  heroku git:clone -a <app>
  ```
  Heroku itself calls this a last resort; it only works for apps deployed with `git push heroku`, not the GitHub integration or the container registry (for those, the user's own repo is the source). Run the clone locally under the user's own login; the git endpoint is not guaranteed to accept a scoped token.

  Buildpack apps have no Dockerfile, so write one: base image matching the runtime, copy the app, install dependencies, and make the Procfile's worker command the CMD in exec form. Dockerfile gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "python worker.py"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly. Install `ca-certificates` in slim images. Push to a repo the user controls, then:
  ```bash
  maritime create <name> --repo https://github.com/<user>/<repo> --json
  ```

**Env vars.** Config vars export cleanly in shell format. Write them to a local file, review it (keep `DATABASE_URL`, `REDIS_URL`, and the API keys the worker reads; drop web-only vars), import, then destroy the file:

```bash
heroku config -a <app> --shell > ./heroku-migration.env
maritime env import <agent> ./heroku-migration.env --reload --json
rm ./heroku-migration.env
```

Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each Scheduler job and clock entry as a Maritime trigger: dashboard, agent page, Triggers pane, cron type, using the converted expression. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. Remember that timers inside a sleeping VM do not fire; a bring-your-own-code agent must serve `GET /schedules`, use the SDK scheduler observer, or be created `--always-on`. Rule of thumb: a former always-running worker dyno wants `--always-on`; a Scheduler job wants a cron trigger with auto-sleep, which is usually cheaper than the dyno hours it replaces.

## Step 4: Verify before touching Heroku

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real scheduled firing and check its output against a known-good run from `heroku logs --process-type scheduler -a <app>` (or `--process-type worker`). Older heroku CLIs called this flag `--ps`; if either spelling errors, `heroku logs --help` settles it. Both sides can usually run in parallel; that is the point of leaving Heroku untouched. One caution: a worker draining a shared queue or writing non-idempotent output will double-process during the overlap. If that matters, keep the overlap window short or point the Maritime agent at a staging target first.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on Heroku, so they run them with their own credentials. You never run them.

1. Scale the moved processes to zero (reversible): `heroku ps:scale worker=0 -a <app>`, and `clock=0` if there is one. `worker=1` restores Heroku in seconds.
2. Remove the Scheduler jobs in the dashboard at `https://dashboard.heroku.com/apps/<app>/scheduler`. No CLI for this either; re-adding a job by hand is the rollback.
3. Watch Maritime for a few days: `maritime logs <agent> --json`.
4. The common case ends here: the web dyno keeps serving the site, the app keeps running with `worker=0`, and the bill drops to web only. Stop; do not destroy anything.
5. Only when the entire app is retired: `heroku apps:destroy -a <app> --confirm <app>`. This deletes the app's add-ons and their data with it, including Heroku Postgres. Capture and download a final backup first (`heroku pg:backups:capture -a <app>`, then `heroku pg:backups:download -a <app>`), and only destroy an app whose database the agent no longer uses.
6. If a migration token was minted in the safety section, revoke it: `heroku authorizations` to find the id, then `heroku authorizations:revoke <id>`. If the migration ran inside a Maritime agent, also `maritime env remove <agent> HEROKU_API_KEY`.

## What stays on Heroku

Be upfront about this list rather than letting the user discover it:

- **Heroku Postgres and Key-Value Store add-ons** (the latter is Heroku Redis's current name): keep them. Copy `DATABASE_URL` and `REDIS_URL` into the Maritime agent's env vars and keep using them over the public connection string, which is exactly how the dynos reached them anyway. One catch: Heroku states plainly that add-on config var values can change at any time (provider maintenance, failover, or a manual `heroku pg:credentials:rotate`), so pull fresh values at cutover with `heroku config:get DATABASE_URL -a <app>` and expect to update the agent's env if a rotation happens later.
- **The web dyno**: if it serves the site, it stays, along with its custom domains and SSL. Moving a public website is a different project from moving its background jobs; do not conflate them.
- **Other add-ons (SendGrid, Mailgun, Papertrail, and friends)**: the services keep working. Any add-on-provisioned key the worker used is already in the config vars export from Step 3 and travels with the env import.

## Official Heroku documentation

The exact Dev Center pages a migrating user needs, in the order this skill touches them:

- [Heroku Scheduler](https://devcenter.heroku.com/articles/scheduler): the three frequencies, UTC times, dashboard-only job management, and the `scheduler.X` dyno naming.
- [Procfile](https://devcenter.heroku.com/articles/procfile): process types, why `web` is the only type that receives HTTP traffic, and how `worker` and `clock` lines are declared.
- [Configuration and config vars](https://devcenter.heroku.com/articles/config-vars): how config vars work, plus the warning that add-on-set values can change at any time.
- [OAuth authorizations and scopes](https://devcenter.heroku.com/articles/oauth): the scope table behind the `read-protected` recommendation in the safety rules.
- [Heroku CLI authentication](https://devcenter.heroku.com/articles/authentication): `HEROKU_API_KEY` and how it overrides the stored login.
- [Dyno types](https://devcenter.heroku.com/articles/dyno-types): what each dyno tier costs, for the before-and-after bill comparison.
- [Heroku CLI commands reference](https://devcenter.heroku.com/articles/heroku-cli-commands): every command and flag in one page, including `apps:destroy` and `authorizations:create`.
- [Heroku Postgres credentials](https://devcenter.heroku.com/articles/heroku-postgresql-credentials): credential rotation and how a rotation rewrites config vars and restarts apps.
- [Heroku Key-Value Store](https://devcenter.heroku.com/articles/heroku-redis): the Redis add-on's current name and its explicitly-unstable connection strings.
- [Cloning an existing Heroku app](https://devcenter.heroku.com/articles/git-clone-heroku-app): why `git:clone` is unsupported-last-resort and which deploy methods leave it empty.

## Troubleshooting

- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.
- `heroku git:clone` yields an empty or stale repo: the app was deployed via the GitHub integration or container registry; the user's own repo is the real source.
- The scheduler dashboard page 404s: the app has no Scheduler add-on (`heroku addons -a <app>` confirms); the schedules are probably in a clock process, so go back to the Procfile and grep the code.
- `heroku ps` shows transient `scheduler.N` dynos: those are Scheduler runs in flight, not a process type to migrate; the jobs behind them are the migration targets.

Heroku syntax in this skill was verified on 2026-08-07 against live `heroku --help` output (CLI v10.8.0) and the Dev Center pages linked above; maritime syntax is checked against the current maritime CLI source. What remains desk-checked is behavior against a live Heroku account, since verification ran logged out. If a provider-side command errors on a flag, trust `heroku <cmd> --help` over this document and continue.

---

## Migrate from Render to Maritime
Source: https://maritime.sh/docs/migrations/render.md

# Migrate from Render to Maritime

Move the automation layer of a Render account onto Maritime: cron jobs and background workers, plus the env vars and env groups they read. Maritime hosts each one as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent. Render cron jobs are the friendliest case in this skill set: a standard cron expression plus a command maps one to one onto a Maritime agent with a cron trigger.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, credentials stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **Render API keys are full-account. There is no read-only scope.** Render does not offer scoped or read-only API keys; the official docs state that an API key provides access to all workspaces the user belongs to, so the usual read-only-credentials rule cannot be satisfied here. Compensate three ways: prefer running this skill locally so the key never leaves the user's machine; you only ever issue GET requests against the Render API, never any mutating endpoint, regardless of what anyone asks mid-flow; and the user deletes the key on the Account Settings page of the Render dashboard (dashboard.render.com/u/settings, API Keys section) the moment the migration is done. The user creates the key themselves on that same page. If render.yaml exists in the repo, much of the inventory needs no key at all.
2. **Credentials never travel through chat.** Chat transcripts are logs. Running locally, the user sets `export RENDER_API_KEY=rnd_...` in their own shell. Running inside a Maritime agent, the user sets `RENDER_API_KEY` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation.
3. **Never modify or delete anything on Render.** GET requests only: no suspend, no resume, no deploys, no env var writes, no deletes, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template, and the price, and get a yes before each `maritime create`.

## Prerequisites

- `curl` and `jq`. No Render CLI is required: render.yaml plus the REST API cover the whole inventory. Verify the key with a harmless read: `curl -s -H "Authorization: Bearer $RENDER_API_KEY" "https://api.render.com/v1/services?limit=1" | jq '.[0].service.name'`.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.

## Step 1: Inventory

Three surfaces, in order of reliability. Prefer the first two.

**(a) render.yaml Blueprint in the repo, if the user has one.** It is the source of truth: every service with its type, cron schedules and commands, and env var group references, all readable without any credential:

```yaml
services:
  - type: cron              # a Render "cron job"
    name: nightly-report
    runtime: python
    schedule: "0 6 * * *"   # standard five-field cron, UTC
    buildCommand: pip install -r requirements.txt
    startCommand: python report.py
  - type: worker            # a Render "background worker"
    name: queue-drainer
    runtime: node
    startCommand: node worker.js
    envVars:
      - fromGroup: shared-config   # pulls in every var from that env group
envVarGroups:
  - name: shared-config
    envVars:
      - key: API_BASE
        value: https://api.example.com
```

**(b) The REST API**, for accounts managed through the dashboard instead of a Blueprint:

```bash
# type is one of: web_service, background_worker, cron_job, static_site, private_service
curl -s -H "Authorization: Bearer $RENDER_API_KEY" \
  "https://api.render.com/v1/services?limit=100" \
  | jq -r '.[] | .service
      | select(.type == "cron_job" or .type == "background_worker")
      | [.id, .name, .type, (.serviceDetails.schedule // "-"), .repo, .branch] | @tsv'
```

The list pages (default 20, max 100 per call); with more than 100 services, follow the `cursor` field on the last item via `?cursor=...`.

**(c) The Render CLI**, only if the user already lives in it: `render services -o json --confirm` (CLI v2: `-o json` for machine output, `--confirm` skips interactive prompts; non-interactive runs authenticate with the same `RENDER_API_KEY` env var already exported above). The CLI was rewritten for v2 (github.com/render-oss/cli) and flags have churned between major versions; if this errors, run `render --help` and fall back to render.yaml or the REST API above, which are the stable surfaces.

Cron jobs and background workers are the agent-shaped workloads: report generators, scrapers, queue drainers, sync jobs, Slack/Telegram bots. Present the inventory to the user as a table (service, type, schedule, repo, what it appears to do) and let them pick what moves. Web services and static sites usually stay behind (see the end of this document).

## Step 2: Map

| Render concept | Maritime concept |
|---|---|
| Cron job (schedule + command) | Agent + trigger (cron schedule) |
| Background worker | Agent (bring-your-own code, always-on or auto-sleep) |
| Service env vars + env groups | Agent env vars, AES-encrypted at rest |
| render.yaml `buildCommand` / `startCommand` | Dockerfile `RUN` / `CMD` |
| Service logs in the dashboard | Agent logs (`maritime logs`) |
| Render Postgres / Key Value | Stays on Render; external connection string in agent env vars |

Schedules need no translation. Render cron jobs already use standard five-field cron expressions evaluated in UTC, so the expression copies into a Maritime trigger verbatim. Keep the trigger timezone UTC unless the user says otherwise.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is arbitrary code (a cron command, a worker loop).** Render deploys straight from the user's git repo, so Maritime targets the same repo:
  ```bash
  maritime create <name> --repo https://github.com/<user>/<repo> --json
  ```
  The catch: most Render services use native runtimes (Python, Node, Ruby) and have no Dockerfile, and Maritime needs one. Writing it is porting work, not a click; say so, and budget an hour, not a minute, whenever the service leans on Render-native build steps (runtime autodetection, predeploy commands, build filters). The minimal pattern translates render.yaml directly:
  ```dockerfile
  FROM python:3.12-slim
  RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
      && rm -rf /var/lib/apt/lists/*
  WORKDIR /app
  COPY . .
  RUN pip install --no-cache-dir -r requirements.txt   # was buildCommand
  CMD ["python", "worker.py"]                          # was startCommand
  ```
  Dockerfile gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "python main.py $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly, exec form, no shell. And install `ca-certificates` in slim images (done above) or every outbound HTTPS call fails.

**Env vars and env groups.** The API covers both, still GET-only. Per-service vars first; note this endpoint returns only vars set directly on the service, never the values of linked env groups:

```bash
curl -s -H "Authorization: Bearer $RENDER_API_KEY" \
  "https://api.render.com/v1/services/<service-id>/env-vars?limit=100" \
  | jq -r '.[].envVar | "\(.key)=\(.value)"' > ./render.env
```

Env groups have their own endpoints. List them (each group's `serviceLinks` names the services that use it), then append the right group's values to the same file:

```bash
curl -s -H "Authorization: Bearer $RENDER_API_KEY" \
  "https://api.render.com/v1/env-groups?limit=100" | jq -r '.[] | [.id, .name] | @tsv'
curl -s -H "Authorization: Bearer $RENDER_API_KEY" \
  "https://api.render.com/v1/env-groups/<env-group-id>" \
  | jq -r '.envVars[] | "\(.key)=\(.value)"' >> ./render.env
```

(Values are also readable by the user in the dashboard, per service and per env group, if they prefer to copy by hand.) Then import and destroy the file:

```bash
maritime env import <agent> ./render.env --reload --json
rm ./render.env
```

Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each cron as a Maritime trigger, expression copied verbatim: `maritime triggers create <agent> --type cron --cron "0 6 * * *" --json`, or in the dashboard on the agent page's Triggers pane. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire: a worker that schedules its own jobs with node-cron, APScheduler, or Celery beat will silently miss every run once the VM sleeps. Either serve `GET /schedules`, move the schedule into a Maritime trigger, or mark the agent `--always-on` at create time. A background worker that must consume continuously should be `--always-on`; one that only reacts to chat, webhooks, or triggers can auto-sleep.

## Step 4: Verify before touching Render

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For crons, wait for one real scheduled firing and check its output against a known-good run from the Render service's own logs. Both sides can safely run in parallel; that is the point of leaving Render untouched.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on Render, so they run them themselves, in the dashboard or with their own key. You never run them.

1. Suspend the old service (reversible): the Suspend button on the service page, or `curl -X POST -H "Authorization: Bearer $RENDER_API_KEY" https://api.render.com/v1/services/<service-id>/suspend`.
2. Watch Maritime for a few days: `maritime logs <agent> --json`. If anything is wrong, Resume in the dashboard (or `POST .../resume`) restores Render in one step.
3. Only when satisfied, delete the service from the Render dashboard. The common case is a partial migration: the web service stays and keeps serving, only the crons and workers are deleted.
4. Delete the migration API key on the Account Settings page of the Render dashboard (dashboard.render.com/u/settings). Render keys reach every workspace the user belongs to; do not let one linger.
5. If the migration ran inside a Maritime agent, delete the `RENDER_API_KEY` entry from that agent's dashboard env vars pane and `maritime restart <agent> --json`.

## What stays on Render

Be upfront about this list rather than letting the user discover it:

- **Render Postgres and Key Value (Redis-compatible)**: keep them. Copy the external connection string from the instance's page (Connect menu or Info tab) into the Maritime agent's env vars and keep using it. The internal connection string resolves only inside Render's private network, same region, and will not work from Maritime; always take the external one. Postgres accepts external connections from any IP by default (credentials still required; the user should check their IP allow list has not been tightened). Key Value is the opposite: new instances are not reachable at their external URL until an IP allow list entry exists, so the user adds one on the instance's page themselves (it is a Render settings change, so you never make it) and uses the authenticated external URL.
- **Web services**: usually stay. The typical migration is partial: the web service keeps serving traffic on Render while its crons and workers move to Maritime and keep talking to the same database.
- **Static sites and custom domains**: stay. Maritime is not a static host or CDN, and nothing on Maritime needs the domain unless the user points one at a public web agent, which is a separate task.

## Official Render documentation

Verified pages, exactly the surface this migration touches:

- [Cron jobs](https://render.com/docs/cronjobs): schedule format, UTC evaluation, run and timeout behavior
- [Background workers](https://render.com/docs/background-workers): what workers are; they take no inbound traffic
- [Blueprint YAML reference](https://render.com/docs/blueprint-spec): the full render.yaml spec, including `type: cron`, `type: worker`, `schedule`, `startCommand`, `envVarGroups`, and `fromGroup`
- [The Render API](https://render.com/docs/api): creating and managing API keys from Account Settings
- [API: list services](https://api-docs.render.com/reference/list-services): GET /v1/services, the `type` filter values, limit and cursor paging
- [API: suspend service](https://api-docs.render.com/reference/suspend-service-1): POST /v1/services/{serviceId}/suspend (resume is the adjacent reference page)
- [Environment variables and secrets](https://render.com/docs/configure-environment-variables): per-service vars, env groups, and how groups link to services
- [Create and connect to Render Postgres](https://render.com/docs/postgresql-creating-connecting): internal vs external connection URLs and where to find them
- [Render Key Value](https://render.com/docs/key-value): internal vs external URLs; external access is off until an IP allow list entry exists
- [Render CLI](https://render.com/docs/cli): the v2 CLI, `-o json` output, `--confirm`, and `RENDER_API_KEY` auth

## Troubleshooting

- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.
- The Render service list looks incomplete: the API defaults to 20 per page. Pass `?limit=100` and follow the `cursor`.

The Render REST API paths and response shapes, Blueprint fields, CLI v2 flags, API key scope, and connection string behavior in this skill were verified against render.com/docs and api-docs.render.com on 2026-08-07, and the maritime commands against the current maritime CLI; the end-to-end flow itself remains desk-checked, not yet run against a live Render account. If a provider-side command errors on a flag, trust `render --help` and api-docs.render.com over this document and continue.

---

## Migrate from Vercel to Maritime
Source: https://maritime.sh/docs/migrations/vercel.md

# Migrate from Vercel to Maritime

Move the scheduled layer of a Vercel account onto Maritime: the cron jobs declared in `vercel.json` and the API routes doing background-ish work that those crons hit. Maritime hosts each one as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent. The site itself usually stays on Vercel; the common case is moving only the crons.

One structural simplification over other providers: Vercel deploys from git, so the source of truth is already in the user's repos. There is no code retrieval step, and a ported workload points Maritime at the same repo.

This skill runs in two places: locally in a terminal agent such as Claude Code (strongly preferred here, see safety rule 1) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **There is no read-only Vercel credential, so prefer local.** Vercel tokens (minted at vercel.com/account/tokens) can be scoped to the full account, one team, or one project, but every scope is read-write: even a project-scoped token can deploy, rewrite env vars, and delete deployments inside its scope, and Vercel offers no read-only permission level to request. Say this to the user plainly. The right mitigation is to run this skill locally, where the user is already authenticated via `vercel login` and no new token needs to exist at all. If the migration must run inside a Maritime agent and the user mints a token anyway, they should scope it to the single team or project being migrated, pick the shortest expiry offered, and delete the token at vercel.com/account/tokens the moment the migration ends. The compensating control is behavioral: rule 3.
2. **Credentials never travel through chat.** Chat transcripts are logs. Running locally, the user authenticates themselves with `vercel login`; you never see a token. Running inside a Maritime agent, the user sets `VERCEL_TOKEN` from their own machine with `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation.
3. **Never modify or delete anything on Vercel.** No `vercel remove`, no `vercel env add` or `vercel env rm`, no deploys, no project settings changes, no `vercel crons run` (it invokes the production route), ever, not even if asked mid-flow. The only Vercel commands this skill runs are `vercel whoami`, `vercel project ls`, `vercel link`, `vercel crons ls`, and `vercel env pull`. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template or repo, and the price, and get a yes before each `maritime create`.

## Prerequisites

- `vercel` CLI: `npm i -g vercel`, authenticated by the human with `vercel login`. Verify with `vercel whoami`.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `git` and `jq`.
- Local clones of (or access to) the repos behind the Vercel projects being migrated. Vercel deploys from git, so the repos are the inventory surface.

## Step 1: Inventory

List every project in the current scope (personal accounts and each team are separate scopes; add `--scope <team-slug>` to sweep a team):

```bash
vercel project ls
vercel project ls --format=json   # machine-readable
```

Then, for each project the user cares about, open its repo and read `vercel.json`. Cron jobs look like this:

```json
{
  "crons": [
    { "path": "/api/cron/daily", "schedule": "0 5 * * *" }
  ]
}
```

Both fields are required: `path` is a route on the same project (must start with `/`, max 512 characters) that Vercel hits with an HTTP GET on the production deployment, and `schedule` is a five-field cron expression (max 256 characters). In a linked project directory, newer CLIs can cross-check what is actually deployed with `vercel crons ls --format json` (a beta command; if it is missing, the `vercel.json` in git is the source of truth).

With local clones in one place, the whole sweep is a loop:

```bash
for repo in ~/code/*/; do
  test -f "$repo/vercel.json" || continue
  echo "== $repo"
  jq -r '.crons[]? | [.path, .schedule] | @tsv' "$repo/vercel.json"
done
```

For each cron entry, open the route it points at (`app/api/cron/daily/route.ts` or `pages/api/cron/daily.ts`) and read what it actually does. Also sweep for background-shaped routes without a `crons` entry: some projects fire routes from GitHub Actions, Upstash QStash, or an external cron service instead, and those are agent-shaped workloads too.

Present the inventory to the user as a table (project, cron path, schedule, what the route appears to do) and let them pick what moves.

## Step 2: Map

| Vercel concept | Maritime concept |
|---|---|
| `vercel.json` cron entry | Agent + trigger (cron schedule) |
| API route the cron hits | The agent's job: an instruction to a framework agent, or ported code |
| Project env vars (production) | Agent env vars, AES-encrypted at rest |
| Vercel runtime logs | Agent logs (`maritime logs`) |
| `CRON_SECRET` header check | Unneeded; Maritime triggers fire inside the agent, drop the check |
| Vercel Postgres / KV / Blob | Stays on Vercel; the agent connects over connection strings |

Schedule expressions translate exactly: `vercel.json` crons already use standard five-field cron, evaluated in UTC. Vercel's dialect is a strict subset of standard cron (no `MON`/`JAN` style names, and day-of-month and day-of-week are never both set), so every expression that deployed on Vercel copies over cleanly. Copy each expression into the Maritime trigger unchanged and keep the trigger timezone UTC unless the user says otherwise.

One upgrade to offer while mapping: Vercel's Hobby plan caps crons at once per day and fires them anywhere inside the scheduled hour (Pro and Enterprise get per-minute precision; all plans cap at 100 cron jobs per project). If the user wanted an hourly or minute-precise schedule and settled for daily because of the plan, the Maritime trigger can now be the schedule they originally wanted.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest paths, and the first is usually faster:

- **Recreate the logic as an instruction (often the fastest migration).** A Vercel cron hitting `/api/cron/refresh` is often twenty lines: fetch something, write it somewhere, maybe send a message. Rather than porting the Next.js route, recreate that logic as an instruction to a Maritime framework agent with a cron trigger. Enumerate templates live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
  Then give the agent the task as instructions plus the env vars it needs, and attach the cron trigger. Offer this path first for simple routes; fall back to porting when the logic must stay exact code.
- **Port the route (bring-your-own code).** This is porting work, roughly an hour per project, and you should say so. A serverless handler has no server, so give it a real one: a small Express shim around a JS/TS handler, or FastAPI around a Python one. The shape is:
  ```js
  // server.js: the former route handler behind a real server
  const express = require("express");
  const { runJob } = require("./job");   // logic lifted from app/api/cron/daily
  const app = express();
  app.post("/run", async (req, res) => res.json(await runJob()));
  app.listen(process.env.PORT || 8080);
  ```
  Edge-runtime routes need a Node port first; routes using `@vercel/kv` or `@vercel/postgres` clients work as-is once their env vars come along. Add a Dockerfile:
  ```dockerfile
  FROM node:22-slim
  RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
  WORKDIR /app
  COPY . .
  RUN npm ci --omit=dev
  CMD ["node", "server.js"]
  ```
  Gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "node server.js $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly, as above, and keep `ca-certificates` in slim images or every outbound HTTPS call fails. Because Vercel deploys from git, put the wrapper and Dockerfile on a branch of the same repo the Vercel project already deploys from, then point Maritime at it:
  ```bash
  maritime create <name> --repo https://github.com/<user>/<repo> --json
  ```

**Env vars and secrets.** Pull the production env per project, from inside the repo directory (`vercel link --yes --project <name>` first if the directory is not linked; `vercel env pull` defaults to development, so the flag matters):

```bash
vercel env pull .env.production --environment=production
```

Trim the file before importing: `VERCEL_`-prefixed platform vars and `NEXT_PUBLIC_` browser vars belong to the site, not the agent. Then import and destroy the local file:

```bash
maritime env import <agent> ./.env.production --reload --json
rm ./.env.production
```

Vars marked sensitive on Vercel are non-readable once created, by any interface, `vercel env pull` included; expect them missing from (or blank in) the pulled file, and note that Vercel now defaults new production and preview vars to sensitive. The user re-supplies those values from their own records with `maritime env set`. Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each cron as a Maritime trigger: dashboard, agent page, Triggers pane, cron type, expression copied verbatim, timezone UTC. Scriptable equivalent: `maritime triggers create <agent> --type cron --cron "0 5 * * *" --json`. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire; either serve `GET /schedules`, use the SDK scheduler observer, or mark the agent `--always-on` at create time.

## Step 4: Verify before touching Vercel

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real scheduled firing and check its output against a known-good run from the Vercel dashboard logs. While both schedules are live the job runs twice per tick: harmless for idempotent refresh jobs, not for jobs that send emails or move money. For side-effectful jobs, verify with the manual run above and go straight to cutover instead of letting both fire.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on Vercel, so they run them themselves. You never run them.

1. Delete the `crons` block from `vercel.json`, commit, push. Vercel redeploys from git and the crons stop firing. This is fully reversible: `git revert` plus a push restores them in one deploy.
2. Watch Maritime for a few days: `maritime logs <agent> --json`.
3. **The common case ends here.** The site keeps running on Vercel, only the crons moved, and there is nothing to delete.
4. Only if the whole project is being retired: `vercel remove <project-name>` deletes the project and all its deployments from the scope (`--safe` skips deployments holding an active preview URL or production domain). Check domains and traffic first; this is the irreversible step.
5. If a token was minted for this migration, delete it at vercel.com/account/tokens now. Deleting it there revokes it everywhere at once.
6. If the migration ran inside a Maritime agent, remove `VERCEL_TOKEN` from that agent in the dashboard env vars pane.

## What stays on Vercel

Be upfront about this list rather than letting the user discover it:

- **The site itself.** Vercel is genuinely good at static and SSR Next.js hosting, and Maritime does not replace it. Do not pitch moving the frontend; this skill moves the scheduled layer and leaves the site alone. Preview deployments, ISR, and image optimization are part of the site and stay with it.
- **Vercel Postgres, KV, and Blob**: data services do not move. The Maritime agent keeps calling them over the connection strings that came along in the env pull (`POSTGRES_URL`, the KV REST URL and token, `BLOB_READ_WRITE_TOKEN`). If the project is retired later, those stores must be exported first; flag them in the cutover conversation.
- **Domains and DNS**: stays. Nothing on Maritime needs it unless the user points a domain at a public web agent, which is a separate task.

## Official Vercel documentation

The exact pages a migrating user needs, verified current as of 2026-08-07:

- [Cron jobs overview: how crons fire, expression format, UTC rule](https://vercel.com/docs/cron-jobs)
- [Cron jobs usage and pricing: per-plan counts, intervals, and precision](https://vercel.com/docs/cron-jobs/usage-and-pricing)
- [Managing cron jobs: CRON_SECRET, logs, concurrency, idempotency](https://vercel.com/docs/cron-jobs/manage-cron-jobs)
- [vercel.json configuration reference, including the crons property](https://vercel.com/docs/project-configuration/vercel-json)
- [vercel env CLI reference: env pull, environments, sensitive defaults](https://vercel.com/docs/cli/env)
- [Sensitive environment variables: why some values cannot be read back](https://vercel.com/docs/environment-variables/sensitive-environment-variables)
- [vercel project CLI reference: project ls and its flags](https://vercel.com/docs/cli/project)
- [vercel remove CLI reference: project-name semantics and --safe](https://vercel.com/docs/cli/remove)
- [Access tokens: scoping levels, expiry, where to create and revoke](https://vercel.com/docs/accounts/access-tokens)
- [vercel crons CLI reference (beta): ls, add, run](https://vercel.com/docs/cli/crons)

## Troubleshooting

- `vercel env pull` gave development values: the `--environment=production` flag was missing; pull defaults to development.
- Pulled file is missing some keys, or has them blank: those vars are marked sensitive on Vercel and cannot be read back by any interface; the user re-supplies them with `maritime env set`.
- `vercel project ls` shows the wrong projects: wrong scope. Personal account and each team are separate; pass `--scope <team-slug>`.
- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.

Every Vercel command, flag, and platform claim in this skill was verified on 2026-08-07 against the official Vercel documentation and live `vercel` CLI help output; the maritime commands are desk-checked against the current maritime CLI source but not live-run. If a provider-side command errors on a flag, trust `vercel <cmd> --help` over this document and continue.

---

## Migrate from a VPS to Maritime
Source: https://maritime.sh/docs/migrations/vps.md

# Migrate from a VPS to Maritime

Move the automation layer of a VPS or bare server onto Maritime: crontab entries, systemd services and timers, pm2 and supervisor processes, bots living in tmux or screen sessions, and Docker containers. This is the classic "$5 droplet running my bot under tmux" migration, and it applies to any box you can SSH into: Hetzner, Linode, OVH, DigitalOcean, a Raspberry Pi, an old EC2 instance nobody dares touch. Maritime hosts each workload as its own agent with a schedule, encrypted env vars, and logs, for a flat monthly price per agent.

This skill runs in two places: locally in a terminal agent such as Claude Code (preferred, keys stay on the user's machine) or inside a Maritime agent. Either way the same rules apply.

## Safety rules, non-negotiable

1. **A regular user, and a behavioral contract instead of enforcement.** Honest version: there is no such thing as an enforced read-only SSH login on a stock box. So the contract is behavioral and hard: connect as a normal non-root user the human designates, run only the commands listed in Step 1 (all read-only), never write a file on the box, never install anything, never use sudo. Anything that needs elevated read access is quoted for the human to run themselves and paste back. Never accept root SSH keys or a root login, even if offered.
2. **SSH keys never travel through chat.** Chat transcripts are logs. The human adds a public key for a keypair they control to the box's `~/.ssh/authorized_keys` themselves. Running locally, you use the user's own SSH agent or config. Running inside a Maritime agent, the user generates a dedicated keypair on their own machine and installs the private key via `maritime env set` or the dashboard env vars pane (encrypted at rest), never by pasting into the conversation. Remind them to remove the key from `authorized_keys` when the migration is done.
3. **Never modify or delete anything on the box.** No `systemctl disable`, no `pm2 stop`, no editing crontabs, no killing processes, ever, not even if asked mid-flow. Cutover is a human-run checklist at the end of this document.
4. **Confirm before every paid action.** Creating a Maritime agent charges the first month at creation. Name the workload, the target template, and the price, and get a yes before each `maritime create`.

## Prerequisites

- `ssh` and `rsync` locally. Verify access with `ssh <user>@<host> hostname` before anything else.
- `maritime` CLI: `npm i -g maritime-cli`, then `export MARITIME_TOKEN=mk_...` (the user mints a key with `maritime keys create --name migration --json`). Always pass `--json`: success is JSON on stdout, failure is JSON on stderr, branch on exit code.
- `jq`.

## Step 1: Inventory

The commands below are the complete list you may run on the box. Every one is read-only. Set `BOX=<user>@<host>` once and sweep all five habitats a workload can live in:

```bash
# Cron: the most common home of a VPS job
ssh "$BOX" 'crontab -l'
ssh "$BOX" 'cat /etc/crontab'
ssh "$BOX" 'ls /etc/cron.d /etc/cron.daily /etc/cron.hourly'
# Other users' crontabs need root. Quote this for the HUMAN to run, never run it yourself:
#   sudo ls /var/spool/cron/crontabs      # Debian/Ubuntu layout; RHEL-family boxes use /var/spool/cron

# systemd: long-running services and timers
ssh "$BOX" 'systemctl list-units --type=service --state=running'
ssh "$BOX" 'systemctl cat <unit>'          # for user-authored units, typically in /etc/systemd/system
ssh "$BOX" 'systemctl list-timers'
ssh "$BOX" 'systemd-analyze calendar "<OnCalendar spec>"'  # read-only: normalizes a timer spec, prints its next firing

# Process managers, whichever exists on the box
ssh "$BOX" 'pm2 ls'
ssh "$BOX" 'pm2 describe <name>'
ssh "$BOX" 'pm2 env <id>'                  # env of one pm2 process; treat output as credentials
ssh "$BOX" 'forever list'
ssh "$BOX" 'supervisorctl status'
ssh "$BOX" 'cat /etc/supervisor/conf.d/*'  # Debian layout; if absent, cat /etc/supervisord.conf and follow its [include] section

# Sessions someone left running
ssh "$BOX" 'tmux ls'
ssh "$BOX" 'screen -ls'
ssh "$BOX" 'ps aux'                        # to see what actually runs inside those sessions

# Docker
ssh "$BOX" 'docker ps'
ssh "$BOX" 'docker inspect <container>'    # image, command, env; see the warning below

# General lay of the land
ssh "$BOX" 'ps aux --sort=-%cpu | head -30'
ssh "$BOX" 'date'                          # the box timezone; cron lines run in it
ssh "$BOX" 'ls ~/apps ~/bot ~/scripts'     # guesses; let the ps and pm2 output guide the paths
```

**`docker inspect` output contains env secrets in plain text.** Treat it like a credential: never echo it into chat, never quote it in your summary. Write the values you need straight into a local `.env` file (Step 3) and nothing else.

Version note: pm2, forever, and supervisor drift across versions. If a subcommand or flag above is missing, run `pm2 --help` or `supervisorctl help` on the box and adapt; the intent (list processes, show one process with its env) is stable. Also, `ssh "$BOX" 'pm2 ls'` can fail with "command not found" when pm2 was installed via nvm, because non-interactive shells skip nvm's setup; the fix is the full path, usually `~/.nvm/versions/node/<ver>/bin/pm2`.

Agent-shaped workloads are the ones that wake up, do a job, and go quiet, or sit waiting for messages: cron scripts, report generators, scrapers, Slack/Telegram/Discord bots, queue drainers, sync jobs. Present the inventory to the user as a table (workload, where it lives, schedule or trigger, what it appears to do) and let them pick what moves.

## Step 2: Map

| VPS concept | Maritime concept |
|---|---|
| crontab line / /etc/cron.d entry | Agent + trigger (same cron expression; shift hours if the box is not UTC) |
| systemd timer + oneshot service | Agent + trigger (convert OnCalendar to cron) |
| systemd long-running service | Agent (always-on or auto-sleep) |
| pm2 / forever / supervisor process | Agent |
| Bot in a tmux or screen session | Agent (`--always-on`, or auto-sleep if it only reacts to messages, which is cheaper) |
| Docker container | Agent (often the same Dockerfile, minus the gotcha below) |
| .env files, `Environment=` lines, pm2 env | Agent env vars, AES-encrypted at rest |
| journalctl, pm2 logs, nohup.out | Agent logs (`maritime logs`) |

Crontab lines are already real five-field cron, so trigger expressions copy over unchanged when the box runs UTC; otherwise note the offset from `date`, plan to shift the hour fields when you recreate the trigger in Step 3, and watch for a `CRON_TZ=` line, which overrides the box timezone for that one table. One trap: lines in `/etc/crontab` and `/etc/cron.d` carry a sixth field, the username, between the schedule and the command; take the five time fields only. systemd `OnCalendar` converts mechanically: `OnCalendar=*-*-* 05:00:00` becomes `0 5 * * *`. For anything fancier, `systemd-analyze calendar` from Step 1 prints the normalized form and the next firing; a bare weekday spec implies midnight, so `OnCalendar=Mon..Fri` means Mon through Fri at 00:00:00, cron `0 0 * * 1-5`. Write out the equivalent cron and show the user both forms.

## Step 3: Recreate on Maritime

**Pick the target shape.** Two honest cases:

- **The workload is an LLM-driven bot or assistant.** Recreate it on a Maritime framework template. Enumerate live, never hardcode ids:
  ```bash
  maritime templates --json
  maritime create <name> --template <id-from-that-list> --json
  ```
- **The workload is arbitrary code (a script, a pm2 app, a container).** This is a port, not a copy, and you should say so. Budget an hour, not a click. Pull the code down read-only, then get it into a git repo the user controls:
  ```bash
  rsync -az "$BOX":/path/to/app ./app-copy
  ```
  Add a Dockerfile if there is none. The minimal patterns for a Python and a Node worker:
  ```dockerfile
  FROM python:3.13-slim
  RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
  WORKDIR /app
  COPY requirements.txt .
  RUN pip install --no-cache-dir -r requirements.txt
  COPY . .
  CMD ["python", "main.py"]
  ```
  ```dockerfile
  FROM node:24-slim
  RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
  WORKDIR /app
  COPY package*.json ./
  RUN npm ci --omit=dev
  COPY . .
  CMD ["node", "index.js"]
  ```
  Dockerfile gotcha that will bite: never use a shell-string CMD like `CMD ["sh", "-c", "python main.py $PORT"]`. Maritime's micro-VM init flattens CMD to one string and the VM kernel-panics on boot. Launch a real program directly, as both patterns above do. And keep `ca-certificates` in slim images or every HTTPS call fails. Then:
  ```bash
  maritime create <name> --repo https://github.com/<user>/<repo> --json
  ```

**Env vars and secrets.** Gather from the three places a VPS hides them: `pm2 env <id>` output, `Environment=` and `EnvironmentFile=` lines in the unit files you already read with `systemctl cat`, and `.env` files sitting next to the code. Cat them straight into a local file, never into chat:

```bash
ssh "$BOX" 'cat /path/to/app/.env' > ./vps.env
# append KEY=value lines extracted from pm2 env / unit files / docker inspect by hand
maritime env import <agent> ./vps.env --reload --json
rm ./vps.env
```

Env changes apply on next boot unless you pass `--reload`.

**Schedules.** Recreate each cron line as a Maritime trigger with the same expression: `maritime triggers create <agent> --type cron --cron "0 5 * * *" --json`, or in the dashboard: agent page, Triggers pane, cron type. On backends older than 2026-08-07 the CLI form created triggers that never fired (the config key mismatch is fixed platform-side now), so always confirm with `maritime triggers list <agent> --json` and watch the first firing. Maritime triggers do not inherit the box's timezone: assume UTC, shift the hour fields when the box runs something else, and confirm the first real firing time in Step 4. OpenClaw-family agents can equivalently use their native cron, which Maritime syncs. For bring-your-own-code agents remember that timers inside a sleeping VM do not fire; either serve `GET /schedules`, use the SDK scheduler observer, or mark the agent `--always-on` at create time. A tmux-resident bot that only reacts to inbound messages can usually auto-sleep instead, which is cheaper.

## Step 4: Verify before touching the box

Do not proceed until the Maritime side has done the job at least once:

```bash
maritime status <agent> --json | jq -r '.status'
maritime chat <agent> "run your task once now and report what you did" --json | jq -r '.response'
maritime logs <agent> --level error --json
```

For scheduled workloads, wait for one real scheduled firing and check its output against a known-good run from the box (the human pulls `journalctl -u <unit>` or `pm2 logs` for comparison). Both sides can safely run in parallel; that is the point of leaving the box untouched.

## Step 5: Cutover and decommission (human runs every command here)

Print this checklist for the user. These are write operations on the box, so they run them over their own SSH session. You never run them.

1. Pause the old job, reversibly. Cron: comment out the line with `crontab -e` (uncomment to restore). systemd: `systemctl disable --now <unit>` (restore with `systemctl enable --now <unit>`). pm2: `pm2 stop <name> && pm2 save` (restore with `pm2 start <name> && pm2 save`). supervisor: `supervisorctl stop <name>`. tmux bot: detach and stop the process inside the session.
2. Watch Maritime for a few days: `maritime logs <agent> --json`. If anything is wrong, the one-line restore above brings the box back instantly.
3. Only when satisfied, remove: delete the unit files and `systemctl daemon-reload`, `pm2 delete <name> && pm2 save`, delete the crontab lines for real, remove the code directory.
4. Remove the migration public key from `~/.ssh/authorized_keys` on the box.
5. Cancel the VPS itself only if it hosts nothing else. Before canceling, check for other tenants of the box: databases, nginx sites, mail, backup jobs, a friend's side project. The inventory in Step 1 shows workloads, not everything; have the human do a final sweep before the box dies.

## What stays on the box

Be upfront about this list rather than letting the user discover it:

- **Databases on localhost (Postgres, MySQL, Redis).** Moving data is out of scope for this skill. Two honest options: switch the agent to a managed database it reaches over TLS, or keep the VPS alive as a database-only box the agent connects to over the public internet with a firewall rule. Either way, every `localhost` or `127.0.0.1` connection string you find in env vars is a decision point: it breaks the moment the worker moves. Flag each one explicitly and let the user choose before cutover.
- **Nginx sites, static sites, reverse proxies.** They stay. Maritime hosts agents, not the box's websites.
- **Mail servers, backup targets, VPN endpoints, anything else on the box.** Stays. This is exactly why step 5 warns about other tenants before canceling.

## Reference documentation

The authoritative pages for every source-side tool this skill touches. All links checked 2026-08-07.

- [crontab(5): tables for driving cron](https://man7.org/linux/man-pages/man5/crontab.5.html) - field layout, the CRON_TZ variable, system vs per-user crontabs
- [systemd.time(7): calendar event syntax](https://man7.org/linux/man-pages/man7/systemd.time.7.html) - the OnCalendar grammar you are converting to cron, with normalization examples
- [systemd.timer(5): timer units](https://man7.org/linux/man-pages/man5/systemd.timer.5.html) - how OnCalendar timers activate their matching service
- [systemctl(1)](https://man7.org/linux/man-pages/man1/systemctl.1.html) - list-units, cat, list-timers, and the enable/disable --now pair used at cutover
- [journalctl(1)](https://man7.org/linux/man-pages/man1/journalctl.1.html) - pulling a known-good run with -u for the Step 4 comparison
- [pm2 process management](https://pm2.keymetrics.io/docs/usage/process-management/) - list, describe, stop, delete, save
- [supervisord: running supervisorctl](https://supervisord.org/running.html) - supervisorctl actions and config file locations
- [tmux(1)](https://man7.org/linux/man-pages/man1/tmux.1.html) - list-sessions (ls) and attach
- [docker inspect](https://docs.docker.com/reference/cli/docker/inspect/) - the JSON you mine for image, command, and env
- [rsync(1)](https://man7.org/linux/man-pages/man1/rsync.1.html) - archive-mode pulls of the code directory

## Troubleshooting

- `maritime create` exits with HTTP 402: billing gate, the account needs a plan or payment method. The error detail names the fix; show it verbatim.
- `agent_unavailable` on chat: the agent is not running, `maritime start <agent> --json` first.
- Env var changes not visible: they land on next boot; use `--reload` or `maritime restart <agent>`.
- A 404 on exec/file operations usually means the agent is asleep, not gone. Start it, wait a few seconds, retry. Do not recreate.
- SSH prompts for a password: the public key is not installed for that user. Stop and ask the human to add it; never type or handle a password.
- `crontab -l` says "no crontab for <user>": that user has none; the job may live under another user (the human runs the sudo listing from Step 1) or in `/etc/cron.d`.

Command syntax in this skill was verified on 2026-08-07: box-side commands against the man pages and vendor docs linked above (cron, systemd, pm2, supervisor, tmux, Docker, rsync), maritime commands against the CLI source, and the Docker base image tags against Docker Hub. It has not been live-run against a real VPS, so if a box-side command errors on a flag, trust `<tool> --help` on the box over this document and continue.