@serve.zone/onebox

Onebox is a self-hosted application platform for a single server. It combines Docker, SmartProxy routing, a typed web control plane, app templates, platform services, and containerarchive-powered backups into one Deno-distributed binary.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit 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/ 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 SmartProxy-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.
• Stores platform state in SQLite.
• Can provision app dependencies through local platform providers: MongoDB, MinIO/S3, ClickHouse, MariaDB, and Redis.
• 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

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

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

Installation

Install the released binary:

curl -sSL https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh | sudo bash

For published wrapper builds, install with pnpm:

pnpm add --global @serve.zone/onebox

This repository currently marks the package as private; use the install script or a released wrapper package when available.

The package wrapper downloads the platform-specific binary during postinstall. Current release assets are named for Linux, macOS, and Windows on x64/ARM64 where available.

Quick Start

Run a foreground development instance:

onebox server --ephemeral

Open the dashboard:

http://localhost:3000

Default bootstrap credentials are created when no admin user exists:

username: admin
password: admin

Change the default password immediately after first login.

Deploy a simple service:

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

For production, install and run the systemd service:

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 SQLite path is ./.nogit/onebox.db relative to the current working directory.

CLI Reference

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 SmartProxy.
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.
status	Print JSON system status.
upgrade	Install the latest released binary. Requires root.

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

Configuration Notes

Useful settings include:

Setting	Purpose
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.
dcrouterWorkHosterId	Optional work hoster identity used for route ownership.
dcrouterTargetHost	Optional target host advertised to dcrouter.
dcrouterTargetPort	Optional target port advertised to dcrouter.

Example:

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 catalog data from serve.zone/appstore-apptemplates and caches it briefly. Templates can declare platform requirements, so installing an app can automatically provision MongoDB, S3-compatible storage, ClickHouse, Redis, or MariaDB resources and inject the resulting credentials as environment variables.

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, platform resource metadata, supported platform data, and optionally Docker images into a content-addressed archive repository. The code also keeps compatibility paths for older .tar.enc backup flows.

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

Development

Requirements:

• Deno for the application runtime.
• pnpm for package scripts.
• Docker for any runtime path that initializes Onebox fully.

Common tasks:

pnpm run watch
pnpm build
deno task test
deno task test:watch
deno task compile

Source map:

Path	Purpose
mod.ts	Deno entry point.
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/reverseproxy.ts	SmartProxy 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/	SQLite 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 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.