Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
142 lines (108 loc) · 3.67 KB

DEPLOYMENT.md

File metadata and controls

142 lines (108 loc) · 3.67 KB

Deployment

GenericAgent can be deployed as a developer CLI, a globally installed local tool, or a packaged artifact with the TypeScript TUI bundle embedded.

Deployment Modes

Mode Use when Command
Source checkout Active development uv run GenericAgent
Global local tool Personal daily CLI uv tool install .
Wheel/package artifact Distribution or CI artifact python -m build after bundling TUI
Headless command runner CI / scripted tasks gae chat /status, gae task <iodir>

Local Tool Deployment

cd ga_engineered
uv sync --extra dev
SKIP_INSTALL=1 ./scripts/build_tui.sh
uv tool install --force .

Smoke test:

GenericAgent --version
gae doctor
gae status
gae chat /status

Package Build

The wheel must include src/generic_agent_engineered/_tui_dist/bundle.js.

cd ga_engineered
uv sync --extra dev
SKIP_INSTALL=1 ./scripts/build_tui.sh
uv build

Then install from dist/:

uv tool install --force dist/generic_agent_engineered-*.whl

Runtime Directories

Set a stable home directory on deployed machines:

export GENERIC_AGENT_CONFIG_DIR=/opt/generic-agent/state
mkdir -p "$GENERIC_AGENT_CONFIG_DIR"

GA_CONFIG_DIR is the short alias. GENERIC_AGENT_HOME is still honored for older service files, and CLAUDE_CONFIG_DIR is accepted as a free-code compatibility fallback when no GenericAgent-specific variable is present.

Recommended layout:

/opt/generic-agent/
├── app/                 # source checkout or installed package reference
├── state/               # GENERIC_AGENT_CONFIG_DIR
│   ├── settings.json
│   ├── config.json
│   ├── history.jsonl
│   ├── auth.json
│   ├── agents/
│   ├── cache/
│   ├── projects/
│   ├── sessions/
│   ├── skills/
│   ├── tasks/
│   ├── telemetry/
│   ├── transcripts/
│   └── state/sessions.sqlite
└── logs/                # shell/service logs if you wrap the CLI

Keep auth.json private:

chmod 700 "$GENERIC_AGENT_CONFIG_DIR"
chmod 600 "$GENERIC_AGENT_CONFIG_DIR/auth.json"

Browser Bridge Deployment

For machines that need live browser tools:

uv sync --extra bridge
uv run gae bridge --port 18765

Operational notes:

  • WebSocket listens on the selected port, default 18765.
  • HTTP /link listens on PORT+1, default 18766.
  • The Chrome extension must be loaded from assets/tmwd_cdp_bridge/.
  • If another bridge already owns the port, the gateway will report the bridge as unavailable rather than killing the existing process.

For long-running local use, run the bridge in your terminal multiplexer or service manager and start the TUI separately.

CI Smoke Test

Example CI sequence:

uv sync --extra dev
SKIP_INSTALL=1 ./scripts/build_tui.sh
python3 -m json.tool tasks.json >/dev/null
python3 -m compileall -q src tests
python3 -m unittest tests.test_commands
cd ui-tui && npm run type-check && npm test
uv run gae --version
uv run gae chat /status

Use focused Python tests if the runner cannot bind browser bridge ports or does not have every optional dependency installed.

Release Checklist

Before publishing or pushing a deployment branch:

  1. Build the TUI bundle.
  2. Run Python compile/tests.
  3. Run TypeScript type-check/tests.
  4. Verify tasks.json is valid JSON.
  5. Verify gae doctor, gae status, and gae chat /status.
  6. Confirm no secrets are present in .generic-agent/, shell history, or docs.
  7. Update CHANGELOG.md and tasks/TASK_REPORT.md for user-visible changes.

See Release Checklist for the standing project gates.