Container images

You already have an agent, written your way? Deploy its container image instead of a harness. Waken turns the image into a persistent machine: your program keeps its disk and its memory, sleeps when idle, wakes on the next message, and can be rewound like any other agent.

The contract

Your program listens on the port given in $PORT (18789 by default) and answers two routes:

• GET /health: answer 200 when you are ready.
• POST /chat with {"message": "...", "source": "api"}: answer with plain text, or JSON with one of response, reply, message, text or output.

import os, json
from http.server import BaseHTTPRequestHandler, HTTPServer
 
class Agent(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200); self.end_headers(); self.wfile.write(b"ok")
    def do_POST(self):
        body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        reply = json.dumps({"response": "You said: " + body["message"]}).encode()
        self.send_response(200); self.end_headers(); self.wfile.write(reply)
 
HTTPServer(("0.0.0.0", int(os.environ.get("PORT", 18789))), Agent).serve_forever()

Deploy

curl -X POST https://api.waken.sh/agents \
  -H "Authorization: Bearer $WAKEN_KEY" \
  -d '{
    "name": "my-agent",
    "image": "ghcr.io/you/my-agent:1.4",
    "env": { "OPENAI_API_KEY": "sk-..." }
  }'

Optional: command replaces the image's entrypoint and command, port changes the port, and disk_gib gives it a bigger disk. The first deploy of an image takes a few seconds while it is downloaded. After that, a new agent from the same image starts in under two seconds.

Private registry (Docker Hub, GHCR, GitLab, your own): add "registry_auth": {"username": "...", "password": "..."}. A token works as the password. The credentials are used for that download only and never stored.

Then talk to it like any agent, with POST /agents/{id}/message. Files, commands, logs, variables, schedules and checkpoints all work the same. Keep what must survive in /data or anywhere on disk: the whole disk persists.

Memory and disk can change later with PUT /agents/{id}/size, like any agent: the machine restarts on its bigger disk in a few seconds, and your program is relaunched. Every image machine also gets a swap file the size of its memory, so a peak spills to disk instead of killing your program.