zk-data-agent/README.md

# K1412 Agent

[中文文档](README.zh-CN.md) · English

K1412 Agent is a multi-user web coding Agent. Every user request enters the
same independently evolvable Agent loop; its scheduler, context policy, memory,
tools, evidence rules, and child Agents are owned by this repository.

The production instance is available at <https://agent.k1412.top>.
Architecture, Agent internals, and the experiment board are published at
<https://agent.k1412.top/doc/>.

## Architecture

```text
browser
  |
  v
Open WebUI (auth, RBAC, chat history, UI)
  |
  v
Agent Runtime (model gateway + Agent loop)
  |
  v
Workspace Gateway (identity, policy, audit)
  |
  v
one Docker workspace per Open WebUI user on a dedicated execution host
```

Open WebUI is pinned and lightly patched. Its picker exposes only four model
names and a separate read-only thinking status. Provider URLs, provider model
IDs, API keys, tool server settings, system prompts, and runtime parameters
remain server-side.

Model identity and thinking control are intentionally separate:

| UI model | Provider model | Thinking | Reasoning effort |
| --- | --- | --- | --- |
| Luna | `ChatGPT-5.6:Luna` | On, no effort levels | — |
| Terra | `ChatGPT-5.6:Terra` | On, no effort levels | — |
| Sol | `ChatGPT-5.6:Sol` | On, no effort levels | — |
| DeepSeek V4 Pro | `deepseek-v4-pro` | On | Extreme (`max`) |

The three Ollama models advertise `thinking`, but they are Qwen-family models
with a boolean thinking switch rather than GPT-OSS-style low/medium/high
effort levels. Luna, Terra, and Sol are different models, not three reasoning
settings for one model.

## Local development

1. Copy `.env.example` to `.env` and fill in the secret values. Never commit
   `.env`. Generate new values with `./scripts/init-secrets.sh`.
2. Build the user workspace image:

   ```bash
   docker compose --profile build-only build workspace-image
   ```

3. Start the stack:

   ```bash
   docker compose up --build
   ```

4. Open <http://localhost:3000>. New users register as `pending` and require
   approval by the bootstrap administrator.

Provider credentials are intentionally not stored here. Keep them only in the
protected deployment `.env`.

## Tests

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
```

Run the complete local verification path, including the real Docker isolation
test, with:

```bash
./scripts/verify.sh
```

Run a live Agent evaluation in a unique, disposable, network-disabled Docker
workspace with:

```bash
set -a
source /path/to/protected/deepseek.env
set +a
.venv/bin/python scripts/eval-live-work.py --model deepseek-v4-pro
```

The evaluator reports latency, token usage, tool counts, completion evidence,
and the generated file listing. It removes only the uniquely named evaluation
container, volume, and network unless `--keep-workspace` is supplied.

Run the disposable six-service integration stack with a deterministic fake
model provider and exercise registration approval, the Agent loop, workspace
isolation, and file delivery with:

```bash
./scripts/verify-e2e.sh
```

The E2E stack and its test-only volumes are removed on exit. Set
`E2E_KEEP_STACK=1` only when you need to inspect the running containers.

Audit every finished service and workspace image, requiring consistent Python
environments, zero known Python vulnerabilities, and zero fixable
High/Critical image vulnerabilities, with:

```bash
./scripts/audit-images.sh
```

Generated files are available from the **工作区文件** button beside the model
selector. Users can browse directories, download one file, or download the
current directory as a `.tar.gz` archive. Browser requests are authenticated by
Open WebUI and re-signed for the Workspace Gateway; no internal key is exposed.

## Documentation

- [中文文档索引](docs/README.zh-CN.md)
- [Documentation index](docs/README.md)
- [Architecture and Agent loop](docs/architecture.md)
- [Agent loop implementation](docs/agent-loop.md)
- [Experiment system](docs/experiments.md)
- [Project history and decisions](docs/project-history.md)
- [Open WebUI integration](docs/openwebui-integration.md)
- [Infrastructure map](docs/infrastructure.md)
- [Development and verification](docs/development.md)
- [Operations runbook](docs/operations.md)
- [Security model](docs/security.md)

## Deployment

Production uses immutable `linux/amd64` images in
`docker.k1412.top/wuyang/*`, an Unraid Compose Manager project, private
service networking, and a single public HTTPS entry at
`https://agent.k1412.top`.

User workspaces run through SSH on a dedicated Docker host; application and
database services remain on the NAS.

## License and Open WebUI attribution

The web service is derived from Open WebUI v0.9.6. Open WebUI's copyright,
license, and attribution remain under the upstream Open WebUI License. K1412's
original Runtime, Gateway, deployment, tests, and documentation are Apache-2.0.
This is therefore a mixed-license source repository; the Open WebUI-derived web
layer is not relicensed as Apache-2.0.

The production deployment uses Open WebUI's branding-removal exception for
installations with at most 50 end users in a rolling 30-day period. Public
builds retain upstream branding by default. See
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).