Company OS workspace and AgentChat launch guide

This is the shortest path to a local HSM-II Company OS workspace with AgentChat.

Use this when you want:

• Company Console at http://127.0.0.1:3050
• hsm_console API at http://127.0.0.1:3847
• Postgres-backed Company OS records
• AgentChat connected to the Company OS runtime
• worker execution, tasks, files, memory, governance, and run evidence

One command

From the repository root:

bash scripts/company-os-agentchat-ready.sh

Root shortcut:

./company-os-agentchat-ready.sh

The script starts the canonical local stack and waits for:

http://127.0.0.1:3847/api/company/health
http://127.0.0.1:3050/api/agent-chat-runtime

Open:

http://127.0.0.1:3050/workspace/start

If ports are stale

For local development when old API or UI listeners are holding ports:

bash scripts/company-os-agentchat-ready.sh --restart

This stops listeners on the configured API/UI ports, starts the canonical stack, reports endpoints, and keeps monitoring health in the foreground.

Lower-level launcher

The lower-level command is:

bash scripts/company-os-up.sh

Use it when you want direct control over environment variables or process startup.

Prerequisites

You need:

• Rust and Cargo
• Node.js and npm
• Postgres, usually through Docker Desktop or Colima
• an LLM provider path

Provider options:

• OpenRouter: set OPENROUTER_API_KEY or HSM_OPENROUTER_API_KEY
• Ollama: install a local model and set the Ollama model env vars
• UI inspection only: open the workspace without expecting full execution

Postgres options:

• default Docker/Colima path
• or set HSM_COMPANY_OS_DATABASE_URL
• and set HSM_COMPANY_OS_SKIP_DOCKER=1 when using your own Postgres

Verify health

API:

curl -sfS http://127.0.0.1:3847/api/company/health

AgentChat runtime:

curl -sfS http://127.0.0.1:3050/api/agent-chat-runtime

Static product website, when served separately:

http://127.0.0.1:4242/

What success looks like

After startup, you should be able to:

1. Open /workspace/start.
2. Select or create a company.
3. Open AgentChat.
4. Ask a simple operational question.
5. See runtime status in the UI.
6. For substantive work, see task/run evidence instead of only chat text.

Try:

Create a task to review the onboarding email flow. Assign a likely owner and explain what evidence you need before making customer-facing changes.

Expected behavior:

• AgentChat answers in normal language.
• The system keeps the turn tied to Company OS context.
• Consequential work should identify owner, evidence, and approval needs.

Integrating a company

Start simple:

1. Create the company workspace.
2. Add the first tasks or goals.
3. Upload key files and policies.
4. Add company memory only when it is reusable.
5. Configure DRI/owner policy for high-risk domains.
6. Connect external systems only for workflows you actually want agents to touch.
7. Add evals for routing, evidence, and escalation once the workflow matters.

Useful integration APIs and docs:

• Tasks and goals: src/company_os/http_tasks.rs, src/company_os/http_goals.rs
• Workspace files: src/company_os/workspace_files.rs
• Memory: src/company_os/company_memory.rs, src/company_os/memory_retrieval.rs
• Connectors: docs/company-os/connectors-sessions-and-triggers.md
• Governance: src/company_os/http_governance.rs
• AgentChat routes: web/company-console/app/api/agent-chat-reply
• Worker execution: src/company_os/http_worker.rs

Model profiles

Use the cheapest model that can complete the job safely.

Recommended default:

• local or cheap model for casual chat, summaries, and low-risk work
• stronger model for ambiguous planning, code, finance, legal, HR, customer impact, or policy work
• human approval for high-risk mutations

Ollama example:

HSM_LLM_PROVIDER_ORDER=ollama \
DEFAULT_LLM_MODEL=qwen2.5:1.5b \
HSM_AGENT_CHAT_PROVIDER=ollama \
OLLAMA_MODEL=qwen2.5:1.5b \
bash scripts/company-os-up.sh

Use this as an efficiency mode, not as proof that every task should run on a tiny model.

Stop and cleanup

Stop foreground services:

Ctrl+C

The Postgres container is left running by default.

Stop the local Postgres container:

bash scripts/company_os_postgres.sh down

Troubleshooting

If the UI loads but AgentChat is degraded:

• check http://127.0.0.1:3050/api/agent-chat-runtime
• check provider keys or Ollama model availability
• check that hsm_console health is live
• restart with --restart if old listeners are stale

If Cargo fails in a restricted terminal:

bash scripts/cargo-reliable.sh build

If Docker is not available:

• start Docker Desktop or Colima
• or provide HSM_COMPANY_OS_DATABASE_URL
• set HSM_COMPANY_OS_SKIP_DOCKER=1

What not to require

Do not require these for the basic Company OS operator path:

• Hermes
• Claude harnesses
• OpenCode
• optional sidecars
• Power mode
• external eval harnesses

Those are advanced or optional lanes. The core product path is:

Company Console + hsm_console + Postgres + AgentChat + native worker