Skip to content

quick-start.md

Latest commit

 

History

History
86 lines (62 loc) · 2.6 KB

quick-start.md

File metadata and controls

86 lines (62 loc) · 2.6 KB
Raw

Quick Start

This guide starts with the embedded Web Workspace, then shows the scriptable HTTP example for automation and integration work.

1. Clone and test

git clone https://github.com/colinagent/opagent.git
cd opagent
go test ./opagent-runtime/... ./opagent-server/...

2. Start the Web Workspace

scripts/start-web.sh

The browser opens ~/.opagent/workspace as the default Workspace and creates the directory when needed. Choose Models and enter the model API type, Base URL, API Token, and Model ID. The API Token is written to ~/.opagent/configs/user/models.json but is never returned to the browser after it is saved.

Open another directory explicitly when needed:

scripts/start-web.sh /absolute/path/to/project

The page includes a read-only file tree and text preview plus a full-access Workspace Agent with read, write, edit, and shell tools. Each browser tab owns one Workspace; Open workspace opens another Server-local directory in a new tab. See Web Workspace for remote port forwarding and security rules.

3. Run one scriptable HTTP chat

The example creates configs/user/models.json, installs its example Agent, starts a temporary Server binary, creates a thread, and prints the streamed SSE response. It refuses to overwrite an existing model config or Agent.

export OPAGENT_MODEL_ID='your-model-id'
export OPAGENT_MODEL_API_KEY='your-api-key'
export OPAGENT_MODEL_BASE_URL='https://your-provider.example/v1'

# Optional: openai-responses (default), openai-completions, anthropic, or gemini
export OPAGENT_MODEL_API='openai-responses'

examples/http-chat/run.sh

The default base directory is ~/.opagent. To keep the example isolated, use a new explicit directory:

export OPAGENT_BASE_DIR="$(mktemp -d)"
examples/http-chat/run.sh

The script leaves Runtime data in OPAGENT_BASE_DIR so you can inspect the thread JSONL and configuration. Its temporary binary and process are removed.

4. Run the Server yourself

go run ./opagent-server/cmd/opagent-server --workspace /absolute/path/to/project

Read the local capability token:

TOKEN="$(tr -d '\r\n' < "$HOME/.opagent/run/local-connection-token")"
curl http://127.0.0.1:19531/version

Then follow the request shapes in Server API. All /v1 routes require X-OpAgent-Connection-Token; health and version probes do not.

Next steps