# 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
bash scripts/company-os-agentchat-ready.sh
```

Root shortcut:

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

The script starts the canonical local stack and waits for:

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

Open:

```text
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
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
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:

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

AgentChat runtime:

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

Static product website, when served separately:

```text
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:

```text
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:

```bash
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:

```text
Ctrl+C
```

The Postgres container is left running by default.

Stop the local Postgres container:

```bash
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
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:

```text
Company Console + hsm_console + Postgres + AgentChat + native worker
```