@askalf/agent is the device-side half of an askalf workforce. You run it on a machine you want the fleet to be able to act on — a server, a laptop, a remote box — and it opens a persistent WebSocket to your askalf forge. From then on, agents in the fleet can run shell commands or Claude Code on that machine, see what's installed, and stream results back.
It's not a chat client, an MCP server, or an autonomous coder. It's a connector — the substrate side of "agents can do real things on real computers."
npm install -g @askalf/agentRequires Node 22+. For Claude Code execution, install @anthropic-ai/claude-code globally as well.
askalf-agent connect <api-key> --url ws://your-forge:3005 --name laptop --installWrites config, registers with the forge, installs a system service that auto-starts. Close the terminal — the agent keeps running.
| Command | What it does |
|---|---|
connect <key> |
Connect to a forge. Add --install to also register as a service. |
disconnect |
Stop the running daemon. |
status |
Show connection + service state. |
scan |
List the device's discoverable capabilities (CPU, RAM, installed tools, Claude Code presence). |
doctor |
Diagnose common setup issues and offer fixes. |
daemon |
Run in foreground. Mostly useful for debugging — --install is the normal path. |
install-service |
Install the service after a connect without --install. |
uninstall-service |
Remove the service. |
| Flag | Description | Default |
|---|---|---|
--url <url> |
Forge WebSocket URL | wss://askalf.org |
--name <name> |
Device display name in the dashboard | system hostname |
--install |
Install as a service after connecting | — |
-v, --version |
Print version | — |
-h, --help |
Print help | — |
| OS | Backend | Auto-start |
|---|---|---|
| Linux | systemd unit | on boot |
| macOS | launchd plist | on login |
| Windows | Scheduled Task (or nssm if installed) |
on login |
your device askalf forge
┌──────────────┐ ┌──────────────────────┐
│ askalf-agent │ ──── wss ──────► │ dispatcher │
│ │ ◄─── task ────── │ agent fleet │
│ shell │ ──── stream ───► │ dashboard / discord │
│ Claude Code │ ──── result ───► │ │
│ device tools│ └──────────────────────┘
└──────────────┘
- Heartbeat every 30s with memory and uptime.
- Auto-reconnect with backoff after a disconnect.
- Capability scan on registration and on demand — reports CPU, RAM, OS, and presence of
git,docker,node,npm,python,gh,claude, and more. - 5-minute subprocess timeout by default per task.
- Streaming output — the dashboard sees what the task prints, line by line, while it's still running. A final result with token + cost numbers follows.
import os from 'node:os';
import { AgentBridge, scanCapabilities } from '@askalf/agent';
const bridge = new AgentBridge({
apiKey: process.env.ASKALF_AGENT_KEY!,
url: 'wss://your-forge.example.com',
deviceName: 'edge-laptop',
hostname: os.hostname(),
os: `${os.type()} ${os.release()}`,
capabilities: scanCapabilities(),
});
await bridge.connect();Most users want the CLI. This is for embedding the connector in something larger.
Building in public — real today:
- systemd restart can corrupt the stored apiKey (Linux). A
systemctl restart askalf-agentre-encrypts the config and, in some cases, leaves the apiKey unrecoverable. Until the upstream fix lands, recover withaskalf-agent disconnect && askalf-agent connect <key> --install. - Per-user/machine key binding. Keys are bound to the user that ran
connecton the machine that ran it. Switching Linux users on the same box means minting a new key, not reusing the old one. - Older
wsversions reject base64-encoded API keys as subprotocols. If you embedAgentBridgein a project with an olderws, pin to^8.20.0or move the key to theAuthorizationheader.
- Node 22+
@anthropic-ai/claude-codeglobally installed, if you want the fleet to run Claude Code tasks here- A reachable askalf forge (
npx create-askalforcurl -fsSL https://get.askalf.org | bash)
| Project | What it does |
|---|---|
| askalf/platform | The forge + dashboard the agent connects to. |
| @askalf/dario | Local LLM router. Use your Claude Max subscription as an API. |
| @askalf/hands | Computer-use SDK. Agents drive a browser. |
| @askalf/deepdive | Deep-research SDK with citation tracking. |
MIT — see LICENSE.
askalf.org · npm · @ask_alf
This is one of the open-source building blocks from Sprayberry Labs — an independent studio (Atlanta, GA) that ships bespoke software and fixed-price code & security audits, delivered with the AI workforce these tools are part of.
Got a codebase that needs an expert read? → Scan a repo — free mini-audit, or see the $1,500 fixed-price Audit and build Sprints. · sprayberrylabs.com · hello@sprayberrylabs.com