@askalf/agent

@askalf/agent

connect any device to your askalf fleet

askalf.org · @ask_alf · Changelog

What this is

@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."

Install

npm install -g @askalf/agent

Requires Node 22+. For Claude Code execution, install @anthropic-ai/claude-code globally as well.

One-command setup

askalf-agent connect <api-key> --url ws://your-forge:3005 --name laptop --install

Writes config, registers with the forge, installs a system service that auto-starts. Close the terminal — the agent keeps running.

Commands

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.

Options

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	—

Service install

OS	Backend	Auto-start
Linux	systemd unit	on boot
macOS	launchd plist	on login
Windows	Scheduled Task (or nssm if installed)	on login

How it works

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.

Programmatic usage

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.

Known limitations

Building in public — real today:

• systemd restart can corrupt the stored apiKey (Linux). A systemctl restart askalf-agent re-encrypts the config and, in some cases, leaves the apiKey unrecoverable. Until the upstream fix lands, recover with askalf-agent disconnect && askalf-agent connect <key> --install.
• Per-user/machine key binding. Keys are bound to the user that ran connect on the machine that ran it. Switching Linux users on the same box means minting a new key, not reusing the old one.
• Older ws versions reject base64-encoded API keys as subprotocols. If you embed AgentBridge in a project with an older ws, pin to ^8.20.0 or move the key to the Authorization header.

Requirements

• Node 22+
• @anthropic-ai/claude-code globally installed, if you want the fleet to run Claude Code tasks here
• A reachable askalf forge (npx create-askalf or curl -fsSL https://get.askalf.org | bash)

Related projects

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.

License

MIT — see LICENSE.

askalf.org · npm · @ask_alf