Skip to main content
Euca is self-hosted and developer-facing: you run one server, and a client — your code, the CLI, or a model under evaluation — drives it over a single HTTP API. To stand up a server an agent can drive, you pick a hosting class for what it needs (a bare headless host, a GPU host, or a host with an OS device), boot it on a known port bound to localhost, and point your client at it. This page is the operational picture; every port and boot fact below is captured from a running server.

​
Stand up a server an agent can drive

Run the headless host (euca-studio with no window):
It serves the agent HTTP API on 3917 and runs the project’s full game logic, with no window or GPU. Pass a project id (-- --headless <project_id>) to pick which project to serve; with none, the first discovered project is used. It boots immediately and logs its address; the root endpoint is your health check and reports the engine version and tick:
The entity_count and tick reflect the loaded project (the headless host boots a full world), so your numbers will differ; the engine version and liveness are what this check confirms. The server binds 127.0.0.1 (localhost only) on port 3917 — the CLI and the OpenAPI reference default to it too. POST requests must send Content-Type: application/json. POST /step is capped at 10,000 ticks per call, silently — asking for more advances only 10,000:

​
Pick a hosting class

The headless host runs the project’s full game logic each tick — its rules, combat, and any systems the game schedules, plus stepping and forks. Other subsystems need more from the host than a window-less process can provide: On a bare headless host those host-dependent features return an honest error rather than failing silently — e.g. /script/load → No ScriptEngine resource in world, /audio/play → AudioEngine not initialized. Wire the resource (or run on the right hardware) and the same call works.

​
Point clients at a host

There is no EUCA_URL environment variable in the engine — clients take a base URL directly:
  • CLI — euca --server http://localhost:3917 <command> (default is http://localhost:3917).
  • HTTP — your client sets the base URL itself; for a hosted deployment, point it at the host’s URL.

​
Auth posture

  • Local / self-hosted: unauthenticated by default. A localhost server has no global auth gate — token-less calls succeed, so /step, /observe, and /fork just work. This is the intended posture for a trusted dev environment.
  • Opt-in Ed25519 auth is shipped, not scaffolding. Install an AuthStore and POST /auth/login verifies an Ed25519 signature (nit-compatible) and issues a session token; GET /auth/status validates the bearer token; and a per-agent ownership layer (Owner component) gates scoped scene routes (401 on an id mismatch). Without an AuthStore installed it stays off and calls run unauthenticated — auth here is opt-in ownership, not a global gate you must pass.
  • Hosted / benchmark access can additionally layer an API key at the hosting tier (e.g. a reverse proxy) — the truth-hiding evaluation boundary is the relevant access control for graded runs.

​
Platforms & what’s not here

  • Platforms — macOS and Linux. The headless host has no GPU dependency and runs anywhere the engine builds.
  • No managed/cloud offering yet. No Docker image, Kubernetes manifest, CI/CD deploy pipeline, multi-tenancy, rate limiting, or built-in monitoring ships in the repo. Containerizing the single binary is straightforward, but no reference deployment ships today — treat hosting as “run the binary behind your own infrastructure.”

​
Status

  • Shipped — the headless host (euca-studio --headless), localhost bind on 3917, the 10,000-tick step cap, and opt-in Ed25519 auth (/auth/* login + per-agent ownership), off by default. All headless.
  • Not here — a managed/cloud offering, container/orchestration manifests, and a required global authentication gate on the local server (auth is opt-in ownership, not a middleware every call must pass).

The full API

Every endpoint an agent or model can drive a hosted server with, with request and response schemas.