# @serve.zone/onebox

Onebox is a self-hosted application platform for a single server. It combines Docker, CoreTraffic routing, a typed web control plane, app templates, platform services, and containerarchive-powered backups into one NodeNext TypeScript package and service.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## What Onebox Does

Onebox turns a Linux host into a small PaaS that can run your own containers and curated app templates without a separate control plane. It is designed for the "one good server" use case: one machine, one local Docker runtime, one web dashboard, one operational surface.

- Deploys Docker workloads from external images or Onebox App Store templates.
- Uses the local Docker socket and creates the `onebox-network` network automatically.
- Runs workloads as Docker Swarm services when Swarm is active, otherwise as standalone containers.
- Starts a CoreTraffic-backed reverse proxy for HTTP/S routing and WebSocket traffic.
- Serves the web UI and TypedRequest/TypedSocket API through `OpsServer` on port `3000` by default.
- Exposes an admin-authenticated read-only MCP endpoint at `/mcp` for safe service, domain, and platform-service summaries.
- Stores platform state in a local SmartDB database.
- Can provision app dependencies through local platform providers: MongoDB, S3-compatible SmartStorage, ClickHouse, MariaDB, and Valkey.
- Tracks domains, Cloudflare DNS records, ACME certificates, service logs, metrics, backup schedules, and app template metadata.
- Can sync routes and import certificates from an external `dcrouter` gateway when configured.

## Architecture

```text
browser / CLI
    |
    v
OpsServer :3000
  - bundled web UI
  - TypedRequest handlers
  - TypedSocket dashboard events
    |
    v
Onebox coordinator
  - SmartDB repositories
  - Docker manager
  - CoreTraffic route manager
  - DNS and SSL managers
  - platform service providers
  - app store manager
  - backup manager and scheduler
    |
    v
Docker host
  - onebox-network
  - CoreTraffic
  - user services
  - optional platform services
```

`Onebox` is the central class. It initializes the database, Docker, CoreTraffic, DNS, SSL, platform services, App Store, backup subsystem, optional external gateway integration, and the web/API server.

## Installation

Install the latest released Linux binary:

```bash
curl -sSL 'https://code.foss.global/api/v1/repos/serve.zone/onebox/raw/install.sh?ref=main' | sudo bash
```

The installer downloads `onebox-linux-x64` or `onebox-linux-arm64` from the latest Gitea release, installs it under `/opt/onebox`, and links `/usr/local/bin/onebox`. Use `--version vX.Y.Z` to pin a release, `--install-dir /path` to change the target directory, or `--source` to clone the tag and build the NodeNext package locally.

```bash
curl -sSL 'https://code.foss.global/api/v1/repos/serve.zone/onebox/raw/install.sh?ref=main' | sudo bash -s -- --source
```

For source checkouts, install dependencies and build directly:

```bash
pnpm install
pnpm run build
node ./cli.js --help
```

This repository currently marks the npm package as private; use the installer or a source checkout until public npm release packaging is enabled.

## Quick Start

Run a foreground development instance:

```bash
onebox server --ephemeral
```

Open the dashboard:

```text
http://localhost:3000
```

On the first browser visit, Onebox asks you to create the administrator passkey. Enter the short-lived bootstrap code printed in the local Onebox service logs, then complete the browser passkey prompt. The code authorizes first-time enrollment only; Onebox never accepts a human password.

Production passkeys require a stable HTTPS hostname. Persist it before startup with `onebox config set adminUiDomain onebox.example.com`.

`ONEBOX_ADMIN_UI_DOMAIN=onebox.example.com` is an alternative only when added to the Onebox systemd service environment; exporting it in an interactive shell does not update the generated unit. After enrollment, the hostname is pinned to the passkey relying party.

If every passkey for the configured administrator is lost, use local host access to reset enrollment:

```bash
sudo onebox systemd stop
sudo onebox auth reset-passkeys --confirm
sudo onebox systemd start
sudo onebox systemd logs
```

The reset invalidates every passkey and session for the configured administrator. It never enables password authentication. The production database defaults to `/var/lib/onebox/.nogit/smartdb`; use `--database-path` only for a nonstandard installation.

Deploy a simple service:

```bash
onebox service add web --image nginx:latest --domain web.example.com --port 80
```

For production, install and run the systemd service:

```bash
sudo onebox systemd enable
sudo onebox systemd start
sudo onebox systemd logs
```

The systemd unit runs `onebox systemd start-daemon` with `/var/lib/onebox` as its working directory. From source or foreground runs, the default SmartDB path is `./.nogit/smartdb` relative to the current working directory.

## CLI Reference

```bash
onebox <command> [options]
```

Core commands:

| Command | Purpose |
| --- | --- |
| `server [--ephemeral] [--port <port>] [--monitor]` | Start the web/API server in the foreground. |
| `service add <name> --image <image> [--domain <domain>] [--port <port>] [--env KEY=VALUE]` | Deploy a workload. |
| `service list` | List known services. |
| `service start <name>` | Start a stopped service. |
| `service stop <name>` | Stop a running service. |
| `service restart <name>` | Restart a service. |
| `service remove <name>` | Remove a service and its route. |
| `service logs <name>` | Print Docker logs for a service. |
| `appstore list` | List remote app templates. |
| `appstore config <app-id> [--version <version>]` | Print app metadata and version config. |
| `appstore install <app-id> --name <name> [--domain <domain>] [--version <version>] [--env KEY=VALUE]` | Install an app template. |
| `registry add --url <url> --username <user> --password <pass>` | Store external registry credentials. |
| `registry remove --url <url>` | Remove registry credentials. |
| `registry list` | List configured registries. |
| `dns add <domain>` | Add a DNS record through the configured DNS manager. |
| `dns sync` | Sync Cloudflare domains into Onebox. |
| `ssl renew [domain]` | Renew one certificate or expiring certificates. |
| `ssl list` | List stored certificates. |
| `ssl force-renew <domain>` | Force certificate renewal for a domain. |
| `proxy reload` | Reload routes and certificates into CoreTraffic. |
| `proxy test` | Check reverse proxy state. |
| `proxy status` | Print route/certificate counts and ports. |
| `systemd enable` | Install and enable the systemd unit. |
| `systemd disable` | Stop, disable, and remove the systemd unit. |
| `systemd start` | Start Onebox through systemd. |
| `systemd stop` | Stop Onebox through systemd. |
| `systemd status` | Show service status. |
| `systemd logs` | Follow `journalctl` logs. |
| `config show` | Show stored settings with secret values masked. |
| `config set <key> <value>` | Store a setting or supported secret setting. |
| `auth reset-passkeys --confirm [--database-path <path>]` | Locally invalidate every passkey for the configured administrator and prepare fresh enrollment. |
| `status` | Print JSON system status. |
| `upgrade` | Install the latest released package build. Requires root. |

The legacy `nginx` command name is still accepted as an alias for `proxy`, but CoreTraffic is the active proxy backend.

## Configuration Notes

Useful settings include:

| Setting | Purpose |
| --- | --- |
| `adminUiDomain` | Exact HTTPS hostname used as the WebAuthn relying-party ID. |
| `serverIP` | IP address used for DNS records. |
| `cloudflareToken` | Cloudflare API token. `cloudflareAPIKey` is accepted as a legacy alias. |
| `cloudflareZoneId` | Cloudflare zone identifier. |
| `acmeEmail` | ACME account email for certificate issuance. |
| `httpPort` | OpsServer/web UI port. Defaults to `3000`. |
| `metricsInterval` | Metrics collection interval in milliseconds. |
| `backupPassword` | Secret passphrase for encrypted backup repositories. |
| `dcrouterGatewayUrl` | Optional external dcrouter API endpoint. |
| `dcrouterGatewayApiToken` | Optional external dcrouter API token. |
| `dcrouterGatewayClientId` | Optional stable external gateway client identity used for route ownership. |
| `dcrouterTargetHost` | Optional target host advertised to dcrouter. |
| `dcrouterTargetPort` | Optional target port advertised to dcrouter. |

Example:

```bash
onebox config set serverIP 203.0.113.10
onebox config set acmeEmail ops@example.com
onebox config set cloudflareToken cf-token
onebox config set cloudflareZoneId zone-id
```

## App Store

The App Store manager fetches metadata from `serve.zone/appstore` through `@serve.zone/appstore` and caches it briefly. Templates can declare public, secret, and generated environment inputs, container arguments, file-mounted secrets, and platform requirements. Installing an app can automatically provision MongoDB, S3-compatible storage, ClickHouse, Valkey, or MariaDB resources.

Service secrets and provisioned platform credentials are encrypted at rest and resolved only when the workload runtime is created. Environment secrets work with standalone Docker containers and Swarm services. Template `secretFiles` are mounted through Docker secrets and therefore require Swarm mode; Onebox rejects a file-secret workload when the host is using standalone Docker.

```bash
onebox appstore list
onebox appstore config cloudly
onebox appstore install cloudly --name cloudly --domain cloudly.example.com --env SERVEZONE_ADMINACCOUNT=admin:change-me
```

## Backups

Backups are built around `@serve.zone/containerarchive`. Onebox exports service configuration, encrypted service-secret ciphertext, platform resource metadata, supported platform data, and optionally Docker images into a content-addressed archive repository. Compatibility paths for older `.tar.enc` backups migrate legacy plaintext control and platform credentials during restore.

Encrypted service-secret bundles can be decrypted only with the same credential-encryption key. Set the same 32-byte, base64-encoded `ONEBOX_ENCRYPTION_KEY` on another host before restoring there; without an explicit key, Onebox derives one from the hostname and `/etc/machine-id`, so ciphertext is portable only to a host with the same machine identity.

Backup and schedule operations are primarily exposed through the OpsServer/web UI handlers.

## Development

Requirements:

- Node.js for the application runtime.
- pnpm for package scripts.
- Docker for any runtime path that initializes Onebox fully.

Common tasks:

```bash
pnpm run watch
pnpm run build
pnpm test
node ./cli.ts.js server --ephemeral --monitor
```

Source map:

| Path | Purpose |
| --- | --- |
| `cli.js` | Built CLI entry point. |
| `cli.ts.js` | Source CLI entry point for development. |
| `ts/cli.ts` | CLI router and command help. |
| `ts/classes/onebox.ts` | Main coordinator. |
| `ts/classes/docker.ts` | Docker client, networks, containers, and Swarm services. |
| `ts/classes/coretraffic.ts` | CoreTraffic Docker service and Admin API manager. |
| `ts/classes/reverseproxy.ts` | CoreTraffic route and certificate bridge. |
| `ts/classes/platform-services/` | Local platform service providers. |
| `ts/classes/appstore.ts` | Remote App Store catalog and upgrade logic. |
| `ts/classes/backup-manager.ts` | Backup and restore orchestration. |
| `ts/opsserver/` | Web UI server and TypedRequest handlers. |
| `ts/database/` | SmartDB repositories and migrations. |
| `ts_web/` | Dashboard source. |

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH\
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
