Deployment

Deploy Targets

When you deploy an agent from Forge, you choose one of three targets:

Target	Description	Status
Local	The Astromesh node Forge is currently connected to.	Available
Remote Node	Any reachable Astromesh node on the network. Specify the node URL.	Available
Nexus	Managed cloud deployment with multi-tenancy and billing.	Coming soon

Serving Forge

Forge itself is a static SPA (single-page application). It can be served in two modes.

Embedded Mode

In embedded mode, the Astromesh node serves Forge’s static files directly.

Setup:

Build the Forge SPA:
Terminal window
```
cd astromesh-forge
npm run build
```
Copy the build output to the node’s static directory:
Terminal window
```
cp -r dist/* ../astromesh/static/forge/
```

Start the Astromesh node:

uv run uvicorn astromesh.api.main:app --reload

Access Forge at http://localhost:8000/forge.

No URL configuration is needed in embedded mode — Forge uses relative paths (/v1/agents, /v1/tools, etc.) to communicate with the node API.

Embedded mode can be enabled or disabled in the node configuration:

services:
  forge: true  # or false to disable

Standalone Mode

In standalone mode, Forge runs as its own development or preview server, separate from the Astromesh node.

Option 1: npx

npx astromesh-forge --node http://localhost:8000

Option 2: Environment variable

VITE_ASTROMESH_URL=http://localhost:8000 npx astromesh-forge

Option 3: Build and host

Build the static files and serve them from any HTTP server (Nginx, Caddy, S3, etc.):

cd astromesh-forge
VITE_ASTROMESH_URL=http://your-node:8000 npm run build
# Serve the dist/ directory with your preferred HTTP server

CORS Configuration

When running Forge in standalone mode, the Astromesh node must allow CORS requests from Forge’s origin. Add the origin to config/runtime.yaml:

cors_origins:
  - "http://localhost:5173"   # Vite dev server default
  - "https://forge.example.com"  # Production Forge host

Connection Settings

In standalone mode, Forge provides an in-app connection settings dialog where you can update the node URL without restarting. This is accessible from the settings icon in the top toolbar.

The connection URL can be set via (in order of precedence):

In-app settings dialog (stored in browser localStorage).
--node CLI flag at startup.
VITE_ASTROMESH_URL environment variable at build time.
Default: http://localhost:8000.