Skip to content

guardian-intelligence/verself

BranchesTags

Repository files navigation

Verself

Verself sells sandbox compute on Firecracker. Today's surface is a Blacksmith.sh-style GitHub Actions runner replacement; Lambda-style workloads and persistent dev VMs are planned on the same isolation substrate. Customer code runs inside short-lived sandboxes the customer rents — Verself does not host customer applications as managed long-lived services. The hosted runner product contract lives in docs/product/hosted-actions-runners.md.

The platform itself is open-source and self-hostable. The self-hosted bootstrap path is currently an operator/internal surface that renders site artifacts for operator-supplied Latitude.sh bare metal; public SDK and CLI docs lead with hosted verself.sh APIs. See docs/verself-cli.md.

The repo holds services, console, marketing site, and operator tooling, almost entirely self-hosted on bare metal: Forgejo for source, fast CI via Firecracker + ZFS, Grafana + ClickHouse observability (logs, traces, metrics), TigerBeetle for financial OLTP, Stripe integration, Zitadel for enterprise-grade auth, and PostgreSQL for general-purpose RDBMS.

The unified product app lives at https://<domain> (authenticated browser console, public docs, and policy in one TanStack Start app). Public service APIs use per-service origins such as https://billing.api.<domain>, https://sandbox.api.<domain>, and https://iam.api.<domain>. Protocol origins include git.<domain>, auth.<domain>, mail.<domain>, and dashboard.<domain>. See docs/architecture/public-origins.md.

This README is a map. Per-task documentation lives in aspect <task> --help.

Quickstart

Choose the controller platform that is running the repo commands.

Linux x86_64 controller

# 1. Toolchain (one time per controller).
./scripts/bootstrap-linux-amd64
bazelisk mod tidy

macOS Apple Silicon controller

# 1. Toolchain (one time per controller).
./scripts/bootstrap-darwin-arm64
bazelisk mod tidy

Continue from either platform

# 2. Tell OpenTofu where to provision (one time per environment).
cp src/tools/provisioning/terraform/terraform.tfvars.example.json \
   src/tools/provisioning/terraform/terraform.tfvars.json
$EDITOR src/tools/provisioning/terraform/terraform.tfvars.json   # set project_id

# 3. Provision bare metal + render inventory.
aspect dev sops-init
aspect provision apply

# 4. Deploy. Idempotent; safe to repeat.
aspect deploy

# 5. Mint a persona env file and start working.
aspect persona assume platform-admin

Bootstrap

The bootstrap scripts are platform-specific:

Controller platform Entrypoint
Linux x86_64 ./scripts/bootstrap-linux-amd64
macOS Apple Silicon ./scripts/bootstrap-darwin-arm64

scripts/bootstrap-linux-amd64 and scripts/bootstrap-darwin-arm64 are the only sanctioned shell scripts in the repo. Everything else routes through aspect. They pin the three platform-specific bootstrap_pivot binaries that have to land before any Bazel- or Aspect-driven channel can run:

  • bazelisk — sha256-pinned download. Symlinked as bazel next to the installed bazelisk so the Aspect CLI's ctx.bazel.{build,test,run,query} (which spawn bazel directly) resolve through bazelisk's version-pinned downloader.
  • aspect CLI — sha256-pinned download. Hosts every task surface enumerated below.
  • vp (Vite+) — owns vp / vite / rolldown / vitest invocation in the JS workspace at ~/.vite-plus/. Uses vp upgrade <version> for catalog pinning.

Idempotent: short-circuits when the existing binary already matches the pinned sha256 / version. Falls back to ~/.local/bin when the install directory is non-writable and sudo is unavailable, with a PATH warning. Set BOOTSTRAP_INSTALL_DIR to override the default /usr/local/bin.

Versions of record live as constants at the top of each scripts/bootstrap-* entrypoint. The dev-tools catalog under src/tools/dev/ is the version-of-record for everything else; aspect dev install lays those down.

Aspect command map

aspect (no args) lists every group; aspect <group> lists its tasks; aspect <task> --help documents flags. The listing below mirrors the registration in .aspect/config.axl.

Top-level

Task Description
aspect deploy Run the canonical deploy path from authored inputs (--site, --sha).
aspect check Run a verification gate (--kind=go-test|go-vet|go-lint|conversions|ansible|supply-chain|all).
aspect observe Discover or query telemetry (--what catalog|queries|describe|metric|trace|logs|http|service|errors|mail|deploy|supply-chain|workload-identity|temporal).
aspect detect-intrusions Scan verself.host_auth_events for accepted SSH sessions that bypassed Pomerium.

aspect provision

Task Description
apply Provision bare metal through OpenTofu and write host inventory.
destroy Destroy OpenTofu-managed bare metal and remove host inventory.

aspect host

Task Description
edit-secrets Open encrypted host configuration secrets in $EDITOR via sops.
firewall Converge host and owner-local nftables rulesets.
operator-access-handoff Manually hand public SSH :22 to Pomerium and keep direct recovery on :2222.

aspect integrations

Task Description
cloudflare-dns Reconcile Cloudflare DNS records from site integration inputs.

Nomad fan-out is the deploy internal of aspect deploy. Host convergence, OS security patching, guest-image staging, and external integration reconciliation are explicit operator tasks.

aspect db

Task Description
pg list List PostgreSQL databases on the worker (authoritative via \l).
pg shell Open interactive psql against a service database.
pg query Run a SQL query against a service PostgreSQL database.
ch query Run a ClickHouse query on the worker.
ch schemas Print CREATE TABLE statements for every project ClickHouse table.
tb shell Open the TigerBeetle REPL (Ctrl+D to exit).
tb query-accounts Query TigerBeetle accounts through the official client over the operator SSH tunnel.
tb lookup-account Lookup a TigerBeetle account by ID through the official client.

aspect operator

Task Description
device Configure this checkout/device for Pomerium operator SSH and aspect commands.
platform Check or seed the dogfooded platform organization and source repository.

aspect operator device is the entry point for getting a checkout (laptop or new dev VM) onto the host access plane through Pomerium + Zitadel. If the device key is passphrase-protected, load it into ssh-agent before running operator commands:

ssh-add ~/.ssh/id_ed25519
# macOS: ssh-add --apple-use-keychain ~/.ssh/id_ed25519
aspect db ch query --query="SELECT now()"

Use the existing founder/operator Zitadel login during the first Pomerium SSH sign-in; the device key is what becomes newly bound, not a separate human user.

End-to-end design and failure modes: docs/architecture/onboarding-device-or-vm.md.

aspect persona

Task Description
assume Write a persona env file: aspect persona assume <platform-admin|acme-admin|acme-member>.
user-state Set billing fixture state for a persona (plan tier, balance, business-time override).

platform-admin is the dogfooded internal org; acme-* are the customer rehearsal personas. Output env files land under smoke-artifacts/personas/ with 0600 perms.

aspect billing

Task Description
seed Seed billing product catalog and a fixture org.
clock Inspect or mutate billing business time (--set, --advance-seconds, --clear, --wall-clock).
state Inspect billing state for an org.
documents List billing documents for an org.
finalizations List billing finalizations for an org.
events Query recent billing events in ClickHouse.

Naming is deliberately split: --product-id=sandbox is the product catalog/metering ID; --db=billing is the billing-service PostgreSQL database; --db=sandbox_rental is the sandbox-rental-service database.

aspect mail

Task Description
list List recent emails (defaults to agents inbox).
accounts List synced mailbox accounts.
mailboxes List mailboxes for an account (defaults to agents).
read Read a specific email by ID (get IDs from aspect mail list).
code Extract latest 2FA/verification code (defaults to agents).
send Send via Resend (e.g. --to=agents --subject=hello --body='...').
passwords Print Stalwart mailbox passwords for ceo and agents.

aspect artifacts

Supply-chain admission and content-addressed artifact publishing.

Task Description
publish Build and publish content-addressed Nomad artifacts to private Garage.
inventory Inventory supply-chain install/fetch paths or render the artifact policy.
evidence Assert deploy-time supply-chain rows and spans exist in ClickHouse.
admission-evidence Assert artifact admission/install rows and spans exist in ClickHouse.

Artifact admission and install verification are deploy-flow internals. The operator-facing checks assert the ClickHouse evidence emitted by that flow. The supply-chain policy is generated output and lives under src/host/supply-chain/__generated/policy.json (gitignored). Supply-chain checks regenerate it on demand if missing; rerun aspect artifacts inventory --format=policy --write-policy=src/host/supply-chain/__generated/policy.json after changing inventory inputs.

aspect bazel

Task Description
gazelle Regenerate Bazel Go BUILD files via gazelle update.
tidy Update Bzlmod repository wiring (bazelisk mod tidy --lockfile_mode=update).
update Run aspect bazel gazelle then aspect bazel tidy.

aspect dev

Task Description
install Install pinned controller development tools from the dev-tools catalog.
sops-init Bootstrap SOPS + Age encryption.
hooks-install Install repo git hooks via pre-commit.
verself-web Start local verself-web dev tunnels and HMR server (console + docs + policy).

Aspect-built-in groups

Group Description
aspect auth login|logout|whoami Aspect Workflows authentication.
aspect axl add Add an AXL dependency to MODULE.aspect.
aspect github token Mint Aspect-issued GitHub tokens.
aspect delivery Aspect Workflows delivery (CI-only; deduplicated by action digest per commit).
aspect build/test/lint/format Aspect-default Bazel passes.

Architecture references

High-signal documents to read directly:

Licensing

This project is open-source MIT. Most bundled server components (ClickHouse, TigerBeetle, Forgejo, PostgreSQL) use permissive or weak-copyleft licenses with no network-interaction obligations.

Grafana OSS and Stalwart Mail Server are licensed under AGPL-3.0. If you run upstream binaries unmodified (as pinned in the substrate/devtools catalogs), your obligation is to provide users with source links: github.com/grafana/grafana and github.com/stalwartlabs/stalwart.

Your own application code that talks to these services over HTTP/JMAP/SMTP/IMAP remains a separate work. If you modify Grafana or Stalwart and provide the modified services over a network, you must make those modifications available to interacting users. Consult a lawyer for production licensing/compliance obligations.

About

Self-hosted bare-metal PaaS with Forgejo, Firecracker CI, ZFS, ClickHouse observability, TigerBeetle billing, Zitadel auth, and a product console.

guardianintelligence.org

Topics

go typescript clickhouse self-hosted paas zfs bare-metal firecracker zitadel forgejo tigerbeetle

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages