Managed Capabilities

Use nfltr manage to keep one browser-capable tunnel and its paired TCP sidecar alive on a machine, then stage Copilot, browser shells, HTTP apps, commands, log tails, raw TCP services, gRPC services, and embedded SSH shells from the dashboard as durable desired state.

What This Pattern Gives You

Need	Pattern	Why it helps
One long-lived remote entry point	`nfltr manage`	One browser tunnel and one TCP sidecar stay up while the dashboard controls which workloads are mounted.
Dashboard-owned Copilot or AI session	Managed capability `copilot` or `ai`	The dashboard can start, stop, restart, and reopen the same workload later.
Separate operator fallback shell	Managed capability `terminal`	You can keep an AI surface and a manual shell under the same machine identity.
Persisted desired state while the machine is offline	Dashboard-managed capabilities	Edits survive disconnects and reconcile the next time the machine runs `nfltr manage`.

Recommended mental model

Treat nfltr manage as the local runtime and the dashboard as the control plane. The dashboard stores the intent. The machine decides whether it can actually run that intent and reports the result back.

1. Start The Runtime On The Machine

Run nfltr manage on the target machine and leave it running:

nfltr manage \
  --name dev-laptop \
  --api-key "$NFLTR_API_KEY" \
  --http-addr https://nfltr.xyz \
  --basic-auth review:secret

On nfltr.xyz, keep the explicit --http-addr https://nfltr.xyz in examples so the control-plane and share API base are obvious. The current defaults already request a share URL and keep the tunnel in verified mode.

--http-addr is only for dashboard/control-plane polling. Native connection hints shown in the dashboard are derived from --server, so operators get the public tcp-connect and ssh-proxy endpoint instead of an internal control-plane URL.

2. Open The Dashboard Catalog

Sign in to the dashboard.
Find the agent started with nfltr manage.
Open Catalog.
Use the Managed Capabilities section to save or edit desired state.

Each saved capability is polled by the runtime, mounted under /managed/<capability-id>/, and reported back to the dashboard with a runtime state.

3. Field Format

Field	What it means	Example
Type	Kind of workload to launch	`copilot`, `terminal`, `http`
Label	Dashboard display name	`Copilot`, `Shell`
Target	Local URL, path, workspace, shell, or command	`/home/alice/repo`, `/bin/bash`, `http://localhost:3000`
Config	Optional comma-separated `key=value` pairs	`mode=chat`, `lines=200`, `cwd=/home/alice/repo`

mode=chat, cwd=/home/alice/repo
timeout=120, max_input=1048576

4. Working Recipes

Copilot session

Field	Value
Type	`copilot`
Label	`Copilot`
Target	`/home/alice/repo`
Config	`mode=chat`

Use mode=terminal if you want a full terminal-style Copilot UI instead of the lighter chat surface.

Browser shell

Field	Value
Type	`terminal`
Label	`Shell`
Target	`/bin/bash`
Config	leave blank

The current managed terminal runtime launches a local shell executable directly. It does not yet apply a dashboard cwd setting, so change directories after opening the shell.

Other useful surfaces

Type	Target	Config
`http`	`http://localhost:3000`	optional
`serve`	`/srv/docs`	`index=index.html`
`tail`	`/var/log/syslog`	`lines=200`
`command`	`/usr/local/bin/deploy-check`	`timeout=120, cwd=/home/alice/repo`
`ai`	`/home/alice/repo`	`command=copilot, mode=chat`

Native TCP service

Field	Value
Type	`tcp`
Label	`Postgres`
Target	`localhost:5432`
Config	`public_port=15432`

The dashboard shows the exact nfltr tcp-connect ... --server ... command once the runtime reports the service as running.

Managed gRPC service

Field	Value
Type	`grpc`
Label	`Greeter API`
Target	`localhost:50051`
Config	`public_port=50051`

The dashboard shows both the nfltr tcp-connect command and a matching grpcurl -plaintext localhost:<port> hint.

Embedded SSH shell

Field	Value
Type	`shell`
Label	`SSH Shell`
Target	`/bin/bash`
Config	`authorized_keys=~/.ssh/authorized_keys`

You can also use password=secret or no_auth=true. authorized_keys and host_key paths are resolved on the agent machine, so ~/.ssh/authorized_keys is expanded before NFLTR starts the embedded SSH server. The dashboard shows both tcp-connect and ssh-proxy commands for the running shell.

5. Supported Right Now

The current single-tunnel runtime can execute:

http
serve
command
tail
terminal
copilot
claude
codex
ai when config.command is set
tcp
grpc
shell

The dashboard still accepts these forward-compatible types, but the current runtime reports them as unsupported instead of launching them:

watch

6. How Access Works

Browser-capable capabilities still use the normal browse path. The manage landing page lives at the normal browse root:

/browse/<agent-id>/

Each running managed capability gets its own mounted path:

/browse/<agent-id>/managed/<capability-id>/

The dashboard Open button uses that mounted path once the runtime reports it.

Managed native capabilities do not create a browser Open link. Instead, the dashboard row shows the connection hints you need for that workload:

tcp shows nfltr tcp-connect
grpc shows nfltr tcp-connect plus grpcurl
shell shows nfltr tcp-connect, ssh -p ... user@localhost, and ssh-proxy

7. Authentication And Share Behavior

--basic-auth user:pass on nfltr manage protects the manage landing page and every mounted managed capability URL.
/health and /healthz stay unauthenticated.
--share-auth, --share-bearer, --share-header, and --share-ip-allowlist add an extra outer gate on the share URL only.

That means the public share path can have two layers: share policy at the edge, then agent-side basic auth inside the manage runtime.

8. Runtime States

State	Meaning
`planned`	Saved and waiting for the runtime to finish reconciliation.
`running`	Mounted successfully and ready to open.
`stopped`	Stopped intentionally from the dashboard.
`failed`	Launch/build error on the target machine.
`unsupported`	Accepted by the dashboard, but not executable by the current runtime.

9. Troubleshooting

If the agent shows offline, the local nfltr manage process is gone or disconnected.
If a capability saves but never opens, check whether the dashboard row says failed or unsupported. For tcp, grpc, and shell, use the connection hints shown in the row instead of expecting a browser Open button.
If AI screenshot preview is blocked by CSP, the relay must allow blob: image previews on agent-backed pages.

Start one runtime, manage many browser surfaces

Use the dashboard to stage Copilot, shells, HTTP apps, command UIs, and log tails behind one machine identity.

Open Dashboard Manage CLI →