Content
# Assistant
Agentic AI conversational assistant, based on OpenAI Responses API, supporting internet retrieval, file understanding, image generation, user-defined MCP tools, and secure execution of untrusted commands based on microVM sandbox; built-in personalization settings (text preferences, location) and usage billing (balance, fund flow, detailed request usage).
## Feature Showcase
Click on the screenshot to view the original image.
<table>
<tr>
<td width="50%" valign="top">
<a href="./assets/websearch.png">
<img src="./assets/websearch.png" alt="Internet Retrieval and Execution Timeline: The conversation main area displays the streaming response, and the right panel shows the retrieval progress and complete execution steps" />
</a>
<br />
<strong>Internet Retrieval and Execution Timeline</strong>
<br />
<sub>Continuous feedback on retrieval progress during conversation, with the right panel displaying retrieval keywords, sources, and complete tool invocation process.</sub>
</td>
<td width="50%" valign="top">
<a href="./assets/billing.png">
<img src="./assets/billing.png" alt="Usage and Billing: The settings interface displays account balance, balance exchange, fund flow, and usage details" />
</a>
<br />
<strong>Usage and Billing</strong>
<br />
<sub>View account balance, fund flow, and detailed model and tool usage for each request.</sub>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<a href="./assets/mcp.png">
<img src="./assets/mcp.png" alt="User-defined MCP: The model calls the user-defined MCP tool to query nearby stores, menus, and coupons and create orders" />
</a>
<br />
<strong>User-defined MCP</strong>
<br />
<sub>Access your own MCP server, and the model calls custom tools to complete real business operations.</sub>
</td>
<td width="50%" valign="top">
<a href="./assets/personalization.png">
<img src="./assets/personalization.png" alt="Personalization Settings: My location, based on Amap search, positioning, and map selection" />
</a>
<br />
<strong>Personalization Settings</strong>
<br />
<sub>Text preferences and "My Location", based on Amap search, positioning, and map selection.</sub>
</td>
</tr>
<tr>
<td colspan="2" align="center" valign="top">
<a href="./assets/sandbox.png">
<img src="./assets/sandbox.png" width="50%" alt="Isolated Sandbox Execution: Verify PDF digital signature in the sandbox, with the timeline showing sandbox creation, attachment import, and command execution" />
</a>
<br />
<strong>Isolated Sandbox Execution</strong>
<br />
<sub>Execute untrusted commands in the microVM sandbox, with attachments imported on demand, and commands and output visible throughout the process.</sub>
</td>
</tr>
</table>
## Architecture
Tech Stack: Go (Gin API + Worker) · Next.js (React 19) · Kafka Asynchronous Workflow · PostgreSQL / Redis / S3 Compatible Object Storage · Firecracker / CubeSandbox microVM Sandbox.
### Project Directory Structure
```text
├── cmd/ # Executable program entry
│ ├── api/ # Gin REST API server
│ ├── worker/ # Kafka consumer, executing model/tool loop
│ ├── backend/ # Merged backend process (API + Worker)
│ ├── migrate/ # Database migration tool
│ ├── firecracker-bridge/ # Host machine Firecracker sandbox bridge service
│ ├── sandbox-agent/ # Sandbox guest internal agent (attachment writing, etc.)
│ └── password-hash/ # Password hash tool
├── internal/ # Go business package (auth, billing, sandbox, worker, llm, etc.)
├── frontend/ # Next.js frontend (React 19)
├── db/migrations/ # SQL migration files
├── deploy/nginx/ # Nginx gateway configuration
├── prompts/ # System prompts and context compression prompts
├── docs/ # API documentation, etc.
├── assets/ # README screenshots
├── docker-compose.yml # Single-machine deployment
└── docker-compose.dev.yml # Local development infrastructure
```
## Deployment
### Docker Compose Single-Machine Deployment
```bash
cp .env.example .env
# Edit .env:
# - Configure authentication, storage, and agent prompt parameters
# - Production environment must set WEB_ORIGIN to the actual HTTPS address
# - Generate provider credential master key: openssl rand -base64 32
# Write PROVIDER_CREDENTIAL_MASTER_KEY, keep unchanged after deployment
docker compose up -d
```
Default startup `postgres`, `redis`, `kafka`, `minio`, `migrate`, `api`, `worker`, `nginx`, `frontend`, access `http://localhost:8080` in the browser (port controlled by `NGINX_HOST_PORT`). The image is pulled from GHCR by default and can be overridden with `ASSISTANT_IMAGE_PREFIX` / `ASSISTANT_IMAGE_TAG`.
After startup, create provider credentials, models, and published prices through the system management interface, and set the default model.
### Amap (User Location Settings)
The map in personalization settings uses Amap Web JS API 2.0, which requires two keys to be configured in `.env`:
- `AMAP_JS_KEY`: Public Web Key. Injected when the frontend container is started with Compose, and provided to the browser at runtime by Next.js through `/runtime-config.js`, so the same GHCR image can be used for different deployments; restart the frontend container after modification, no need to rebuild the image.
- `AMAP_SECURITY_JS_CODE`: Security key. Passed to Nginx only, used to render `/_AMapService` proxy at startup, not entering the frontend or image layer; returns `503` if not set.
If not configured, the map, search, and positioning are unavailable, and text preferences and saved location text display are not affected.
### Local Development
```bash
docker compose -f docker-compose.dev.yml up -d # Infrastructure + Nginx
go run ./cmd/migrate up # Database migration
go run ./cmd/api # API server :8080
go run ./cmd/worker # Another terminal
cd frontend && pnpm install && pnpm dev # Frontend :3000
```
### Sandbox (Optional)
Sandbox execution is disabled by default (`SANDBOX_EXEC_ENABLED=false`), and does not affect other functions. Enable it and choose `cubesandbox` or `firecracker` through `SANDBOX_PROVIDER`. Switching providers only affects newly created sandboxes: the configuration of the old provider must be retained until the old sandbox enters `destroyed` and can be removed.
#### How to Choose
| | CubeSandbox (Recommended) | Firecracker bridge |
| --- | --- | --- |
| Applicable Scenarios | **Cloud Server**, larger concurrency | Development and testing, small-scale self-use |
| Deployment Form | Independent cluster (control plane + computing nodes) | Single privileged process on the same machine as the host |
| Startup Method | Template snapshot hot start | Cold start each time |
| Preconditions | Any x86_64 Linux machine, may not have nested virtualization capability, but **requires PVM kernel** | Any Linux machine with nested virtualization capability, no need for custom kernel, but requires KVM module |
#### CubeSandbox (Recommended, currently adapted to v0.5.1)
1. **Install Cluster**: Complete deployment according to the official [Quick Start](https://github.com/TencentCloud/CubeSandbox/blob/v0.5.1/docs/en/guide/quickstart.md) - prepare an x86_64 server (ordinary cloud server is sufficient, no `/dev/kvm` required), install PVM host kernel and restart, and install CubeSandbox with one click. If the host provides native `/dev/kvm` (physical machine/bare metal), use native KVM first, and deploy according to [Bare Metal Deployment](https://github.com/TencentCloud/CubeSandbox/blob/v0.5.1/docs/en/guide/bare-metal-deploy.md).
2. **Create Sandbox Template**: According to [Template Overview](https://github.com/TencentCloud/CubeSandbox/blob/v0.5.1/docs/en/guide/templates.md) and [Making Template from OCI Image](https://github.com/TencentCloud/CubeSandbox/blob/v0.5.1/docs/en/guide/tutorials/template-from-image.md), use `cubemastercli tpl create-from-image` to build. Assistant requires the template to contain envd and `/workspace` and enter `READY`, and the returned `template_id` is written to `SANDBOX_CUBE_TEMPLATE_ID`.
3. **Configure Network Isolation and Firewall**:
- **Control Plane**: According to [Network Hardening](https://github.com/TencentCloud/CubeSandbox/blob/v0.5.1/docs/en/guide/network-hardening.md) to tighten binding addresses and firewall - CubeAPI, CubeMaster, Cubelet, MySQL, Redis, and WebUI are placed in the private network, CubeAPI enables `AUTH_CALLBACK_URL` authentication, and CubeProxy only allows API/Worker access.
- **Sandbox Outbound**: Default `SANDBOX_CUBE_ALLOW_INTERNET=false` and `SANDBOX_CUBE_DENY_OUT=0.0.0.0/0`, sandbox cannot access any external address; according to needs, use `SANDBOX_CUBE_ALLOW_OUT` to allow specific domains or CIDR. When filtering by domain, injecting credentials into requests, or auditing each request, use CubeSandbox's built-in CubeEgress outbound proxy, see [Security Proxy](https://github.com/TencentCloud/CubeSandbox/blob/v0.5.1/docs/en/guide/security-proxy.md).
```bash
SANDBOX_PROVIDER=cubesandbox
SANDBOX_CUBE_API_URL=http://cube-api.internal:3000
SANDBOX_CUBE_API_KEY=your-private-api-key
SANDBOX_CUBE_TEMPLATE_ID=tpl-xxxxxxxx
SANDBOX_CUBE_PROXY_NODE_IP=10.0.0.12
SANDBOX_CUBE_PROXY_PORT_HTTP=80
SANDBOX_CUBE_PROXY_SCHEME=http
SANDBOX_CUBE_DOMAIN=cube.app
SANDBOX_CUBE_CLUSTER_ID=production
SANDBOX_CUBE_ALLOW_INTERNET=false
SANDBOX_CUBE_DENY_OUT=0.0.0.0/0
SANDBOX_EXEC_ENABLED=true
```
Note: Initially, it is recommended to set Cubelet's `host.quota.paused_resource_release_ratio` to `0` to ensure that paused sandboxes can be restored and then deleted; CubeSandbox create API does not support service-side idempotence keys, and production environments require monitoring and cleaning up isolated sandboxes produced by lost responses.
#### Firecracker (Development Environment)
Firecracker bridge is a privileged process running on the host machine (requires `/dev/kvm`, TAP device, and iptables permissions), and the API and Worker communicate with it through HTTP:
First, install KVM and Firecracker. The CPU needs to support and enable hardware virtualization (`egrep -c '(vmx|svm)' /proc/cpuinfo` greater than 0).
Debian / Ubuntu (official repository does not have firecracker package, install KVM and use official release binary):
```bash
sudo apt update && sudo apt install -y qemu-kvm
sudo modprobe kvm kvm_intel # AMD CPU: kvm_amd
ARCH="$(uname -m)"
VER=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/firecracker-microvm/firecracker/releases/latest)")
curl -fsSL -o /tmp/firecracker.tgz "https://github.com/firecracker-microvm/firecracker/releases/download/${VER}/firecracker-${VER}-${ARCH}.tgz"
tar -xzf /tmp/firecracker.tgz -C /tmp
sudo install -m 0755 "/tmp/release-${VER}-${ARCH}/firecracker-${VER}-${ARCH}" /usr/local/bin/firecracker
```
Fedora (official repository includes firecracker):
```bash
sudo dnf install -y firecracker qemu-kvm
sudo modprobe kvm kvm_intel # AMD CPU: kvm_amd
```
Arch Linux (firecracker is in the extra repository):
```bash
sudo pacman -S --needed firecracker qemu-base
sudo modprobe kvm-intel # AMD CPU: kvm-amd
```
Verify after installation:
```bash
lsmod | grep kvm # kvm module loaded
[ -r /dev/kvm ] && [ -w /dev/kvm ] && echo OK # /dev/kvm readable and writable
# bridge runs as root without additional authorization; non-root runtime execution
# sudo usermod -aG kvm $USER and re-login
```
Then start the bridge and configure the API / Worker:
```bash
# 1. Prepare Firecracker kernel and rootfs images; rootfs must be built with the current code
# and sandbox-agent (providing attachment write endpoint)
# 2. Start bridge
export FIRECRACKER_BIN=firecracker
export FIRECRACKER_KERNEL_IMAGE=/path/to/vmlinux
export FIRECRACKER_ROOTFS_IMAGE=/path/to/rootfs.ext4
export FIRECRACKER_BRIDGE_ADDR=127.0.0.1:8787
export FIRECRACKER_BRIDGE_TOKEN=your-secret-token # Optional
go run ./cmd/firecracker-bridge
# 3. Configure API / Worker to use bridge in .env
SANDBOX_PROVIDER=firecracker
SANDBOX_BRIDGE_URL=http://host.docker.internal:8787
SANDBOX_BRIDGE_TOKEN=your-secret-token
SANDBOX_EXEC_ENABLED=true
```
Network isolation: default `FIRECRACKER_NET_ENABLED=false`, guest has no network, strongest isolation. Set to `true` and the bridge will create a bridge `fcbr0` on the host machine (default `172.16.0.0/24`), allocate TAP devices to guests, and enable `ip_forward` and MASQUERADE, allowing guests to access the internet through host machine NAT; use host machine iptables to restrict guest outbound direction.
Sandbox lifecycle (common to both providers): automatically stop after idle `SANDBOX_IDLE_STOP_AFTER` (default `15m`), and release and destroy after stopping exceeds `SANDBOX_STOPPED_RETENTION` (default `24h`), see `.env.example` for details.
For more environment variable descriptions, see `.env.example`, and API documentation see [docs/API.md](./docs/API.md).
## Open-Source License
This project is open-sourced under the [Apache License 2.0](LICENSE).
