Skip to main content
Start Hexagon from a source checkout. You will be able to open Console, configure cloud Sandbox/model connections, and let local SDKs discover the workspace.

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.
Use the repository’s local build/install paths. Do not assume similarly named npm/PyPI packages are publicly published. Installation does not install PostgreSQL or create provider accounts.

Start

Clone the main repository and enter it. If you already have this checkout, start at npm ci from its root:
Replace the connection string with your already-created dedicated database. Never reuse an unrelated application’s database. Without 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

  1. Create a provider connection under Infrastructure → Sandbox, validate, and enable.
  2. Configure endpoint, model ID, protocol, and credentials under LLM, validate, and enable.
  3. Select a compatible Harness/connections in API Playground to generate Python or TypeScript code.
An Agent template is optional. Cloud Sandboxes must reach the credential ingress. Opening Console does not prove cloud connectivity. Settings → Network & ingress controls saved deployment settings; restart after changing them. Use a stable external HTTPS ingress or an explicitly selected development tunnel as described in networking. Management-only disabled ingress does not enable protected cloud execution.

Install SDKs

Use a separate Python virtual environment:
The tutorials use this explicit Python path, so opening another terminal does not require activating the environment again. If you installed into a different virtual environment, replace the interpreter path consistently. Build TypeScript from the repository:
Repository programs can import sdk/typescript/dist/index.js. Independent applications can use the local package distribution process. Python Hexagon.local() and TypeScript await Hexagon.local() discover the current workspace without manually copying an owner token. For multiple workspaces, pass data_directory in Python or dataDirectory in TypeScript. Hosted connections use an explicit URL/Token instead of local discovery identity.

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:
The Python package’s minimum interpreter version and the control plane’s Node requirement are separate. For the repository tutorials, use the control plane’s Node requirement even if an SDK package declares a lower minimum.

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:
Stopping the control plane does not delete cloud Sandboxes. Its expiry enforcement cannot run on schedule while stopped. Next: first Session. See local operations and the launcher contract for deployment, proxies, backup, and recovery.

Recorded installation scope

The November 20 isolated source-install check started from a copied current worktree with no node_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.