Prerequisites
- Node.js 22.19.0 or later.
- Running PostgreSQL and a role able to create tables in a dedicated database.
- Python 3.10 or later for the Python SDK.
- cloudflared for temporary development credential ingress; OpenSSH for Instabox.
- A cloud Sandbox account and model endpoint for subsequent real tasks.
Start
Clone the main repository and enter it. If you already have this checkout, start atnpm ci from its root:
DATABASE_URL, the development default is postgres://hexagon@127.0.0.1:55432/hexagon; that does not mean such a database exists.
Doctor checks prerequisites. The launcher applies migrations and manages the local service. On failure, inspect database connectivity and reported missing dependencies before retrying. Preserve data and its matching encryption key; deleting them does not resolve unknown cloud resources.
Open local Console. Private data defaults to .local/control-plane, configurable through HEXAGON_DATA_DIR. A retained database must retain its matching encryption key.
Configure execution
- Create a provider connection under Infrastructure → Sandbox, validate, and enable.
- Configure endpoint, model ID, protocol, and credentials under LLM, validate, and enable.
- Select a compatible Harness/connections in API Playground to generate Python or TypeScript code.
Install SDKs
Use a separate Python virtual environment:Read readiness one layer at a time
doctor currently sets a failing exit code for unsupported Node or an unreachable database. Missing Python, OpenSSH or cloudflared appears in its JSON fields and may still accompany exit code zero. It also checks command availability rather than proving all supported versions or Provider behavior. Its database probe does not prove migration privileges; startup must still apply migrations successfully.
The commands on this page use a POSIX-style shell and local paths. This page does not certify a clean Windows installation or every operating-system/package-manager combination. The local installation contract describes the launcher and distribution boundary; use an environment you can verify rather than inferring OS support from the SDK alone.
After the SDK installation/build steps, these checks import packages without creating Sessions, contacting a model or allocating cloud resources:
Completion and shutdown
Installation is complete when status reports availability, Console opens, and database/workspace identity are usable. Real execution additionally requires validated connections, cloud allocation, and a successful task. Do not record installation as full cloud acceptance. Before planned shutdown, finish/cancel active Runs, close unused cloud Sessions, and confirm cleanup:Recorded installation scope
The November 20 isolated source-install check started from a copied current worktree with nonode_modules, a new data directory and a new dedicated database. npm ci, doctor/start/status, Python virtual-environment installation, TypeScript build, both SDKs’ local discovery, restart and stop passed. The saved definition, owner identity and encryption key survived restart. The service stopped and the temporary database was removed.
This used an existing macOS host with Node 24.8.0, Python, PostgreSQL, OpenSSH, cloudflared and package caches already available; it is not a clean-OS installation claim. Credential ingress was intentionally unconfigured for management-only startup. Continue to the first-Session tutorial for a real cloud task; its independent dual-SDK cloud evidence has its own recorded configuration. A driver-only first attempt used an unsupported tunnel environment value, failed, and was preserved separately before the corrected attempt.