Deploy with your coding agent

Connect your agent

One account works everywhere. Most clients open a browser to sign in, so there is no key to copy or store.

Claude Code, Codex, OpenCode

Add the server once, in the project you work in:

claude mcp add --transport http erawan https://api.erawan.cloud/mcp

A browser opens, you sign in, and you approve the connection. Codex and OpenCode take the same URL in their own MCP settings.

Claude on the web

Settings → Connectors → Add custom connector, then paste https://api.erawan.cloud/mcp and connect. Chat has no filesystem, so your agent sends the files it wrote straight from the conversation.

Anything else, with no account at all

A first deploy needs nothing from you — no email, no password, no confirmation link. Any agent with a shell can ask for a guest session and put a site online in a minute:

curl -sX POST https://api.erawan.cloud/v1/guest

It returns an access token to deploy with, and a keep_url to hand the person it was built for. Opening that link is how the session becomes an account — the same apps, at the same address.

There are no API keys to store. An agent that connects through the browser holds a token of its own, which you can revoke by name in the console.

Your first deploy

You do not call anything yourself. Describe what you want and let the agent work.

Build a FastAPI service that shortens URLs and deploy it on Erawan.
Call it shortener, and tell me the address when it is live.

Apps live at {name}.erawan.app. The console shows the same apps, versions and logs — plus every agent connected to your account, each one revocable.

Sending code

Three ways in, and your agent picks the one that fits where it is running. They all end up in the same place, with the same checks and the same history.

The upload step, for agents with a terminal:

tar -czf - . | curl -sS -X POST https://api.erawan.cloud/upload \
  -H "Authorization: Bearer erw_at_…" --data-binary @-

Runtimes

Erawan works out how to run your project. A Dockerfile wins if you wrote one, then Python, then Node, then a plain website.

Plain websites are the cheap path: they go up in seconds and cost nothing to keep online. In exchange they have no environment variables, no rollback and no running logs — there is no process to have them.

Addons

Ask for one and it appears next to your app, already connected. Your app is restarted with the settings it needs, so there are no connection strings to wire up by hand.

gzip -c dump.sql > dump.sql.gz
erawan addon add postgres myapp
erawan db import myapp dump.sql.gz

One app, more than one process

Most apps are a single process and need nothing here. When a repository runs a web server and a background worker, put an erawan.yaml at its root and deploy as usual — the file is read on our side, so no particular version of the CLI is needed.

version: 1
addons: [postgres, redis]
components:
  web:
    path: .
    port: 8000
    public: true
    resources:
      requests: {memory: 256Mi, cpu: 100m}
      limits:   {memory: 1Gi,   cpu: 500m}
  worker:
    path: .
    args: ["rq", "worker"]

A component can also carry its own name, which is how a product made of a site, an admin panel and an API stays one app. Two ways to give it one — subdomain: claims a name on erawan.app, domain: points a name you own at a part:

components:
  site:
    path: web/dist
    domain: [example.com, www.example.com]
  admin:
    path: admin/dist
    subdomain: acme-admin          # acme-admin.erawan.app
  api:
    path: backend
    port: 8080
    public: true
  worker:
    path: backend
    args: ["rq", "worker"]

Four parts, four addresses: site on two names you own, admin on one of ours, api on the app's own .erawan.app, and worker on none — it is reached by the others and by nobody else, which is what a worker is for.

• args replaces the image's command, which is how two components share one directory and one image. Prefer it to start_command when the repository has its own Dockerfile: start_command only shapes a Dockerfile we generate, so with one in the tree it is read and then ignored.
• Declare resources for every component. What you leave out claims your plan's whole per-app allowance, so four silent components ask for four times what one app is sold and the fourth is refused.
• addons in the file are re-created on every deploy. Removing one with erawan addon rm and deploying again brings it back — take it out of the file instead.
• public: true belongs to exactly one component — the one that answers on the app's own .erawan.app address. Names in domain: are as many as you like, on as many components as you like.
• Declaring a domain: does not claim it. It says which component the name belongs to; whether it points at Erawan is still erawan domain add and the DNS check, so a deploy never fails because somebody has not finished editing their DNS. A name already on another app of the same account is moved by the deploy — no removal, no gap.

Components accept path, port, public, disk, image, user, domain, args, start_command, resources, secrets and addons.

Logins for your users

For an app with customers of its own. Erawan runs the sign-in, so your app never stores a password and never handles a reset. It is an addon like any other: ask for it and the app restarts with what it needs already set.

erawan addon add myapp auth

Your app is a normal OpenID Connect client. Six variables arrive in its environment and nothing else has to be configured:

The three commands you will actually need

erawan auth callback add myapp http://localhost:3000/callback
erawan auth providers set myapp google,email
erawan auth users myapp

A redirect URI has to be allowed before it is used, including the one you develop against. Providers are google, email, github and line. The user list is masked by default — the addresses of your users are not something a terminal should print by accident.

The page your users see

Sign-in and consent are served by Erawan, and by default they carry your app's name and nothing of ours but one line saying which account is being used. Two things are yours to set:

erawan auth theme show myapp
erawan auth theme set myapp --color blue --name "Suea Thong Gym"

The colour is a name from a fixed list — show prints it — and not a hex value: the list is shadcn's, every entry chosen to carry white text, so there is no combination that produces a button nobody can read. It moves the primary button and the focus ring, and nothing else. The name is what appears above the form, up to 32 characters, and cannot mention Erawan: your users type an Erawan password on that page, so a name claiming to be us is the one thing it must not be able to say.

Environment and secrets

Environment is non-sensitive configuration: feature flags, modes, URLs and log levels. Credentials are app secrets. Declare their names at deploy and enter each value once on Erawan's trusted setup page; an agent never carries it.

erawan deploy . --name myapp --secret OPENAI_API_KEY
erawan env set myapp LOG_LEVEL=info
erawan env list myapp
erawan env unset myapp LOG_LEVEL

Plain websites have no environment at all — there is no process to hold one. A site that needs a key needs to be an app.

Your own domain

Attach a name you own. Erawan prints the DNS records to create, watches for them, then issues the certificate itself — there is nothing to upload and nothing to renew. Included on Hobby and up.

erawan domain add myapp app.example.com
erawan domain ls myapp
erawan domain rm myapp app.example.com

A subdomain gets one CNAME. An apex — example.com with no prefix — cannot be a CNAME at all, so that answer is an A record with the address in it, plus a CNAME for www. Some providers call the apex form ALIAS, ANAME or CNAME flattening; if yours offers one, it works as well.

erawan domain ls says what each domain is waiting for, which is usually DNS that has not propagated yet. The .erawan.app address keeps serving throughout, and keeps serving after you remove a custom domain.

Ready-made software

Some things you do not want to write. Point Erawan at the project's own repository and it goes through the same path your own code does — the pre-deploy check, the build, the history, the rollback.

erawan deploy https://github.com/owner/repository --name my-app

Three things to read before you start

A build takes minutes. These take seconds, and they are the three ways deploying somebody else's project actually fails.

1. The Dockerfile, if there is one. It decides everything else, because detection stops there. BuildKit-only syntax — COPY --link, a --chmod with letters in it, RUN --mount — cannot be built here, and it fails at that step, which may be twenty minutes in.
2. What is actually in the repository. The build context is capped at 150MB compressed, and a documentation site, translations and checked-in binaries all count toward it. If the part that runs is one directory, deploy that directory.
3. Whether the source is the image. A project's repository and the container it publishes are often different things: a monorepo builds dozens of packages and none of them the server you meant. If its README tells you to docker run something, use that image in a two-line Dockerfile rather than building the source.

Then find what it needs told to it — the README, a docker-compose.yml, an .env.example. A missing key is a container that starts, crashes and explains nothing.

For code you wrote yourself there is a cheaper check: erawan assess . runs the same gate a deploy runs and changes nothing. It reads a directory, so it cannot check a GitHub URL — for those, deploying is the check, and a failed deploy never replaces a running version.

Deployed something worth other people knowing about? erawan catalog request <name or URL> --why "…" — what people run here is what the list will be built from.

Apps only you can open

Some apps should not be on the open internet — an admin panel, a tool you run for yourself, software that has no sign-in of its own. Put one line in your erawan.yaml and the URL stops answering strangers.

version: 1
access: owner

Anyone opening the app is sent to Erawan's sign-in, and only the account that owns it is let through. Your app is not changed and gets no extra container: the check happens at the front door, before a request reaches it, and what arrives is an ordinary request from a person Erawan has already identified.

One path can stay open. A webhook, a health check or a payment callback is a machine with no session, and the door would send it to a sign-in page. Name the exceptions when you deploy — up to five, matched exactly:

erawan deploy . --access owner --public-path /callback

Exactly, not by prefix: /callback does not also open /callback-admin. / is refused — that is the whole app.

Jobs and schedules

One-off work — a database migration, a script — runs with your app's own code and settings, and you get the output back.

Repeating work is a task: say when, in cron form, and what to run. Nightly reports and clean-ups keep going after you close the laptop. Schedules are in UTC, and deploying a new version moves the tasks across with it.

When a deploy fails

Failures come back with the reason and the end of the log, written so your agent can act on them without you. Usually it just fixes the code and deploys again.

• The build failed. Something went wrong installing or compiling — the build log has the real error, usually a missing dependency.
• It built, then stopped. The app exited or never served. Check that it binds 0.0.0.0 on the port you gave, and that the start command actually starts a server.
• The check blocked it. A password or key was found in the code, or a .env was about to ship. Move those into settings instead of the code, then deploy again.
• It was fine before. Roll back to the last version that worked, then look into it without the site being down.

Tools

What your agent can do once it is connected. You will rarely name these — ask in your own words and it picks.

REST API

Everything the tools above do, an ordinary HTTP request does too — same account, same pre-deploy check, same history. It is what the erawan command talks to, and it is the path for CI, a script, or an agent that has curl and nothing else.

Base URL and credential

https://api.erawan.cloud/v1
Authorization: Bearer erw_at_…

Every credential here ends. There is no key that lives for ever — a secret nobody has to renew is one nobody notices — so an access token is good for an hour and refreshes itself, and a token you make by hand carries an expiry you chose. Four ways to hold one:

• With no account at all. POST /v1/guest takes nothing and returns an access token, a refresh token and a keep_url. Websites only, and gone in 24 hours unless somebody opens that link.
• From the CLI. erawan login signs in through a browser and keeps the tokens in ~/.erawan/cli.json.
• From a machine with no browser — a container, an agent's sandbox, a server over SSH. erawan login --device prints a short code and a URL; you enter the code on any device that does have a browser, and the machine signs itself in. It is the default when the CLI can see there is no browser to open, so an agent usually needs no flag. Do not copy ~/.erawan/cli.json into a box instead: that file's refresh token does not expire and reaches every app in the account.
• From a connected agent. An agent that connected over MCP holds its own token and can call these endpoints directly. Revoke it by name in the console.
• A token you made on purpose — erw_pat_…, for CI or for a machine you trust less than your laptop. erawan token create ci, or Settings in the console. It expires (90 days by default), it does only what you chose — deploy, admin, or both — and --app limits it to named apps. Revoke one without touching the others. A token cannot create another token: minting needs a person signed in.
  Hand it to a machine with ERAWAN_TOKEN, or with ERAWAN_TOKEN_FILE pointing at a file holding it — the file is read again before every request, so a token rotated by whoever wrote it is picked up without a restart. Either beats a stored login and neither is written to disk, so a box that is handed a token needs no credential file at all.

When an hour is up, exchange the refresh token at POST /token with grant_type=refresh_token and the client_id you were given — guest for a guest session. Refresh tokens are single use: each exchange returns the next one.

Installing a pinned CLI

Building the CLI into an image? Pin the version rather than following the latest, and verify it. https://erawan.cloud/dist/SHA256SUMS gives the digest of the wheel currently published, in the format sha256sum -c reads; /dist/latest names the file and /dist/ lists what exists.

# what is published right now, and its digest
curl -s https://erawan.cloud/dist/latest
curl -s https://erawan.cloud/dist/SHA256SUMS

# pin that filename in your image, and move it when you mean to
uv tool install --force "https://erawan.cloud/dist/<the filename above>"

Only the current release is kept under {C}/dist/ — an old wheel served from there is an old wheel somebody installs — so a pinned filename stops resolving when we publish the next one. That is the intended signal: it is a version you chose, and moving it is a decision rather than a side effect of rebuilding.

--force is the part that matters: uv tool upgrade cannot move an install pinned to a wheel URL — uv's receipt holds the old one — so it bumps dependencies and leaves the command missing. The installer verifies this checksum itself; against somebody who controls the site it proves nothing, since they would publish both, but it catches a truncated download, a stale cache, and a wheel that moved under a version you pinned.

A deploy from nothing, in four calls

TOKEN=$(curl -sX POST https://api.erawan.cloud/v1/guest | jq -r .access_token)

curl -sX POST https://api.erawan.cloud/v1/apps \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"hello","files":{"index.html":"<h1>hello</h1>"}}'

curl -s https://api.erawan.cloud/v1/apps/hello -H "Authorization: Bearer $TOKEN"

curl -s "https://api.erawan.cloud/v1/apps/hello/logs?kind=build" \
  -H "Authorization: Bearer $TOKEN"

Deploying

POST /v1/apps takes a name and exactly one source. Re-posting the same name makes a new version and keeps the old one for rollback.

Endpoints

Handing a secret to an app without an agent ever seeing its value has its own endpoints under /v1/secret-actions and /v1/apps/{name}/secret-requests. They are bound to a recent human approval, so they are worth reading in the description below before using them.

When a call fails

Every failure is JSON with an error and usually a hint written for whoever has to act on it.

The full description, generated from the server itself and never written by hand:

https://api.erawan.cloud/v1/openapi.json

/v1 only ever gains things. Fields and endpoints may appear; nothing that is already here changes shape or disappears without a /v2.

For agents

Reading this as an agent? The deploy playbook is one page, written for you:

https://erawan.cloud/llms.txt

Fetch it once before your first deploy. It picks between a shell, an MCP connection and having neither, and covers guest sessions, the pre-deploy check, and what to do when a build fails. https://erawan.cloud/llms.txt is the map of every surface here — it links to that page rather than repeating it.