CyberStrikeAI/docs/en-US/deployment.md

# Deployment Guide

[中文](../zh-CN/deployment.md)

CyberStrikeAI can run as a local testing tool, an internal team service, or a production red-team platform. Treat it as a high-privilege security system: it can execute commands, call MCP tools, manage WebShell connections, and optionally run C2 listeners.

## Prerequisites

- Go for source runs and binary builds.
- Python for some MCP servers and tool scripts.
- SQLite files under `data/`; no external DB is required by default.
- Actual security tools installed in PATH. YAML files under `tools/` only describe commands.
- At least one `ai.channels` entry. Use `provider: openai_compatible` for OpenAI-compatible endpoints, or `provider: claude` for Eino's native Claude component.

Important persistent paths:

```text
config.yaml
data/
tools/
roles/
skills/
agents/
knowledge_base/
chat_uploads/
```

Back these up before upgrades.

## Startup Modes

Local quick start:

```bash
chmod +x run.sh && ./run.sh
```

`run.sh` is the most common startup path for local use, development, small temporary internal deployments, and quick post-upgrade verification.

For long-running service, boot-time startup, managed logs, and crash recovery, prefer a binary managed by systemd.

Source run:

```bash
go run ./cmd/server --config config.yaml
```

Binary build:

```bash
go build -o cyberstrike-ai ./cmd/server
./cyberstrike-ai --config config.yaml
```

The binary still needs `web/templates`, `web/static`, and the runtime resource directories.

## HTTPS and Reverse Proxy

For local testing, self-signed HTTPS is acceptable:

```yaml
server:
  tls_enabled: true
  tls_auto_self_sign: true
```

For production, use real certificates or terminate TLS at a reverse proxy. If the proxy terminates TLS and forwards HTTP to the app, avoid enabling app-side TLS on the same upstream unless `proxy_pass` uses HTTPS.

Nginx must not buffer SSE:

```nginx
proxy_buffering off;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```

## Upgrading

**Prefer the platform's own one-click update** (console Platform management -> One-click update,
`POST /api/system/update/apply`, or `./cyberstrike-ai -update` at a keyboard). It pulls **the remote
this install directory already tracks**: fetch, fast-forward, `go build`, atomic binary swap (the old
binary is kept as `cyberstrike-ai.prev`), while operator content - `roles/ skills/ tools/ agents/
knowledge_base/ data/ config.yaml` - is put aside and restored, and the result names every file it
kept. For a fork this is the only path that does not overwrite you with somebody else's code; when
source is modified locally or the branch has diverged it refuses and says why instead of forcing.
See [the developer guide](developer-guide.md) for the full semantics.

The source is chosen either in the `update` section of `config.yaml` (`remote` or `remote_url`, plus
an optional `branch`) or right on the console page: the official repository, your own fork, or
somebody else's second-development repository are all just this one setting; unset, it follows the
remote this directory already tracks. An installation unpacked from a Release archive (no `.git`)
can be connected from the same page: the preview lists the files the target would replace and the
operator content that is kept, replaced files are backed up under
`.update-backup/<timestamp>/overwritten/`, and confirming turns the directory into a normal
installation with one-click updates.

`upgrade.sh` still works and is now a thin shell over that implementation, with two paths decided by
the installation kind:

- **git work tree**: calls `./cyberstrike-ai -update` directly (building
  `go build -o cyberstrike-ai ./cmd/server` first when there is no binary yet, and failing with
  instructions on installing Go when there is neither). `--check` inspects only, through
  `-check-update`.
- **not a git work tree** (Release tarball install): only here does it fall back to downloading a
  Release tarball and `rsync --delete`-ing it in. The source repository then comes from
  `--repo owner/name` or the `GITHUB_REPO` environment variable, and the built-in default is used only
  when neither is given - with a warning naming which repository the code is coming from.
  `config.yaml`, `data/`, `tools/`, `roles/`, `skills/`, `agents/`, `venv/` (skippable with
  `--no-venv`) and the rollback points `.update-backup/`, `.update-state.json`, `cyberstrike-ai.prev`
  are on the rsync keep list, so `--delete` cannot remove them.

Recommended flow either way:

1. Stop the service.
2. Back up `config.yaml`, `data/` and your custom directories.
3. Pull or replace the new code/binary.
4. Keep your own configuration and add fields the new `config.yaml` example introduced.
5. Start the service and check login, model test, tool list and knowledge-base status.

The one-click update performs step 3 (plus the rebuild); 1, 2, 4 and 5 stay operator decisions - a
database migration does not become compatible just because the binary changed. `upgrade.sh` suits
quick upgrades without compatibility risk; in production still back up first. Python dependencies:
`venv/` is created and managed by `run.sh`, and keeping it means an upgrade does not remove it - only
`--no-venv` deletes it and lets `run.sh` reinstall.

## Rollback

The one-click update leaves its own rollback point: `./cyberstrike-ai -update-rollback`, or the button
on the page, goes back to the commit before that update and puts `cyberstrike-ai.prev` back. It runs
only while HEAD is still the commit that update wrote, so work done afterwards is not discarded.
Content that was put aside also survives under `.update-backup/<timestamp>/`.

Beyond that, roll back together:

- The previous binary or code.
- The pre-upgrade `config.yaml`.
- The pre-upgrade `data/`.

If the new version already wrote database schema changes, rolling back the binary alone may not be
enough; restore the whole backup.

## Deployment Decision Table

| Scenario | Recommended setup | Key settings | Avoid |
| --- | --- | --- | --- |
| Personal testing | `./run.sh` + self-signed HTTPS | `tls_auto_self_sign: true` | Public exposure |
| Internal team | Binary + systemd + internal HTTPS | strong password, audit, backup, IP restrictions | Shared weak password |
| Production red-team platform | Reverse proxy + dedicated OS user + log collection | real certs, proxy auth, C2 only when needed | Direct public admin UI |
| Chat/KB only | Disable C2 and unnecessary MCP | `c2.enabled: false` | All tools enabled by default |
| Tool automation | Isolated workspace + HITL | `workspace_root_dir`, `hitl`, `monitor` | Shell tools globally allowlisted |

## Acceptance Checklist

After startup:

1. Open `/` and verify no HTTP/HTTPS redirect loop.
2. Login and validate `/api/auth/validate`.
3. Run model test in settings.
4. Check tool list and schemas.
5. If KB is enabled, check index status.
6. If external MCP is enabled, verify connection and tool visibility.
7. If C2 is enabled, start and stop a test listener only in an authorized network.
8. Check audit logs for login and config activity.

## Runtime File Layers

- Replaceable: binary, `web/`, default docs/resources.
- Preserve: `config.yaml`, `data/`, custom tools/roles/skills/agents, `knowledge_base`, uploads.
- Cleanup candidates: checkpoints, temporary workspaces, stale payloads, old tool execution records.

## Source Anchors

- App wiring and routes: `internal/app/app.go`
- TLS bootstrap: `internal/app/main_server_tls.go`
- HTTP to HTTPS redirect: `internal/app/main_server_http_redirect.go`
- Config structs: `internal/config/config.go`
- Config apply: `internal/handler/config.go`