Guides

Self-hosting with Docker

Run the gateway, and optionally the control plane, in your own environment with Docker or Compose.

#The gateway

bash
docker run -d --name rakuvo -p 8081:8081 \
-e OPENAI_API_KEY=sk-... -e RAKUVO_TOKEN=$(openssl rand -hex 24) \
<image>/rakuvo:0.1.0 serve -listen 0.0.0.0:8081 -token-env RAKUVO_TOKEN -tool-policy-auto -loop-guard

Everything after the image name is the gateway's own flags; see the configuration reference. Point your agent at http://<host>:8081/v1 and use the value of RAKUVO_TOKEN as its API key.

Pass secrets as environment variables at run time. Do not bake them into an image or put them in a shell history line you share.

#Compose

A docker-compose.yml and an .env.example come with the release. Copy .env.example to .env, fill in your keys, and:

bash
docker compose up -d # the gateway
docker compose --profile control-plane up -d # and the control plane

#The control plane (optional)

The control plane gives you the dashboard, keys, shared settings and usage. It is a second container with a volume for its database:

bash
docker run -d --name rakuvo-api -p 8090:8090 -v rakuvo-data:/data \
-e RAKUVO_ADMIN_TOKEN=$(openssl rand -hex 24) \
<image>/rakuvo-api:0.1.0

Then run the gateway with -api-url and -config-from-api so it takes its layer settings from the dashboard. See API reference.

#Health and upgrades

  • The gateway image checks its own health (rakuvo healthcheck), so docker ps shows whether it is up.
  • To upgrade, pull the new tag and recreate the container. The control plane's data lives in the /data volume.
  • Run docker exec rakuvo /rakuvo version to see which version a container runs.

#What the images contain

Only the compiled programs. There is no source code, no shell and no package manager in them, and they run as a non-root user.