SHARD-657: shard setup sets up a local host or saves a remote connection

[presmihaylov]

Closes SHARD-657.

Why. Nothing takes a new user from an installed binary to a working host or a saved remote connection.

How.

• Look first at services/setup/setup.go: wizard and flags answer the same Questions through UI; cli/setup.go puts the flags before the terminal.
• A failed step prints its Problem under the checklist; setupExit then exits 1 silently, 130 on Ctrl+C.
• The saved connection is the last source after --remote and SHARD_REMOTE. Host-only verbs refuse it.
• Uninstall removes only what /var/lib/shard-setup/manifest.json lists.
• The root help summary is lowercase like every verb; the spec capitalizes it.
• Open question: Should setup offer a shard group for sudo-free local commands (root-equivalent)?

What. shard setup and docs/setup.md. Wizard screens: a throwaway container. Apply screens: a disposable VM.

Apply, gVisor:

Setting up Shard

✓ Check host compatibility
✓ Download and verify required tools
✓ Install gVisor
✓ Create Shard's data directory
✓ Configure the background service
✓ Start the daemon
✓ Verify the daemon connection

Shard is set up, and the daemon is running.
Local commands run with sudo, for example `sudo shard ls`.

Second run:

Shard is already installed

Version:  v0.1.0
Provider: gVisor
Service:  Active

What would you like to do?

❯ Check or repair the installation
  Upgrade Shard
  Uninstall Shard
  Exit

Local, no /dev/kvm:

Choose how Shard isolates your sandboxes:

  Firecracker [Unavailable]
    Requires access to /dev/kvm.
    This machine does not provide it.

❯ gVisor
    Run sandboxes with a protective layer between their programs and Linux.
    Recommended on Linux without hardware virtualization.

  Sysbox
    Run Docker and system services inside your sandboxes.
    Choose this when your workload needs its own Docker environment.

  runc
    Run standard Linux containers that share the host kernel.
    Choose this for trusted workloads that need standard container behavior.

  macOS Virtualization [Unavailable]
    Requires an Apple silicon Mac with macOS 14 or later.
    This machine runs Linux.

Local review, declined:

Checking this machine

✓ Supported operating system and CPU
✓ Provider requirements
✓ Administrator access
✓ Installation paths and permissions
✓ Available disk space and filesystem support
✓ Download access
✓ Existing Shard installation
Ready to set up Shard

Provider:          gVisor
Automatic startup: No

Setup will:
  Install the tools required by gVisor: ip, nft, mkfs.ext4, runsc.
  Install shard and shard-init in /usr/local/bin.
  Create Shard's data directory.
  Leave daemon startup under your control.

Administrator access is required.

Continue? [Y/n] n
shard: setup was cancelled; nothing changed

Local failed check:

Checking this machine

✓ Supported operating system and CPU
✓ Provider requirements
✓ Administrator access
✓ Installation paths and permissions
✓ Available disk space and filesystem support
✓ Download access
✓ Existing Shard installation
✗ Background service support
  Setup configures a systemd service, and systemd does not manage this machine.
  Run shard setup again and choose No for automatic startup.

No installation changes were made.

Remote failed check:

Checking the connection

✗ Reach the server
  Could not reach https://shard.example.com: no such host.
  Check the URL, and that shard serve or the proxy in front of it runs.
○ Verify authentication
○ Read server capabilities
What would you like to do?

❯ Retry
  Edit connection details
  Exit

Remote over http:

Shard server URL:
> http://shard.example.com

HTTP does not encrypt your API key or requests.
Use it only through a trusted encrypted network.

Continue? [y/N]

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
shard	Ignored	Preview	Oct 5, 2026 9:30am UTC