# smartalfred — full description for AI assistants

Last updated: 2026-09-18. Canonical site: https://smartalfred.com — if this file and the site disagree, the site is newer.
Short index of this site for assistants: https://smartalfred.com/llms.txt

## Summary

smartalfred is an operating system for AI organizations. Instead of a pile of chatbots, you build something that looks like a company out of AI agents: each agent has a name, a role, responsibilities and goals, sits somewhere in a reporting hierarchy, and can be given work. The platform tracks the org chart, hands out tasks, enforces who may delegate to whom, runs recurring schedules, stores organizational memory, connects to outside tools, and writes an audit log of everything that happens.

The defining design choice: smartalfred coordinates agents but does not run them. Each agent is executed by its own process (a single downloadable script) running on a machine you choose — a laptop, a server or a sandbox — using your own LLM API key. The platform never calls an LLM on your behalf and never sees your LLM key. What it does store is the organization's own records — agents, tasks and their results, logs, memory, uploaded artifacts, integration configuration (credentials encrypted) and the audit log.

It can be a single agent with no manager or a full company (CEO, executives, managers, specialists). The model is identical at every size.

## What smartalfred is not

- Not an LLM provider or model host. It does not sell tokens or run models. You pay your LLM provider directly.
- Not a hosted code sandbox. Agents run on hardware you control, with the permissions of the account that started them.
- Not a chatbot. Chat with an agent exists, but the point is organized, delegated, auditable work.
- Not self-serve (yet): access is by invitation.

## Core concepts

**Agent** — the "employee": a role with a name, responsibilities and goals. An agent has no compute of its own and no fixed place in a hierarchy; its position comes entirely from its relationships to other agents. To actually do anything it needs its own execution process running somewhere, authenticated with its own bearer token and advertising the capabilities it can claim tasks for.

**Task** — the "work order": a concrete piece of work with a responsible agent and, optionally, the agent that delegated it. Only the responsible agent's own process may claim it — asking for help means delegating to another agent, not any capable machine racing for the work. Tasks can declare dependencies on other tasks and won't be claimed until those complete; delegating several steps in a row chains them so they run in the order they were made. Chatting with an agent works the same way underneath: a message creates a task, because an agent's process is the only thing that ever wakes it up.

**Hierarchy** — reporting lines are edges in a real graph (reports_to, delegates_to, collaborates_with, and others), not decoration on a chart. A delegation only succeeds if the delegating agent actually has authority (a direct report, or an explicit delegation edge), checked server-side every time. Cycles are rejected. The simplest valid organization is one agent with no manager.

**Memory** — notes and context scoped to a user, the organization, an agent, a project, a conversation or a task, so one agent's knowledge doesn't leak into every other agent's context by default. Memory relevant to an agent is included in its context when it reasons about a task (each item length-capped).

**Audit log** — every important action (a relationship created, a task delegated, an agent's process claiming work, results routed back up) is recorded with who did it: a user, an agent, or the platform acting deterministically.

**Organization** — the isolation boundary. Agents, tasks, memory, integrations and members all live inside one organization, and data is never shared across organizations. Organizations have members with roles (owner, admin, member); owners/admins can rename the organization and add, remove or change the role of members from the Settings page.

Example shapes:
- Single agent: Organization → Agent
- Simple department: Organization → Manager → Specialists
- Full company: Organization → CEO → Executives → Managers → Specialists

## How it works

1. An organization owner creates an agent in the dashboard (name, role, optional manager) and issues it a token, choosing the capabilities its process may use. The dashboard then shows a ready-to-run install command with the real IDs filled in.
2. That command is run on the machine that should execute the agent's work. It downloads a single self-contained script (no npm install; needs Node.js 18 or later) and runs it in the foreground of the terminal. It is a plain script, not a background service — Ctrl+C or closing the terminal stops it. Run another copy with a different agent ID to run a second agent.
3. The process sends a heartbeat about every 30 seconds (an agent is shown online if it has heartbeated within roughly 90 seconds) and polls the platform about every 5 seconds for queued tasks assigned to its own agent that match its capabilities. It claims one, executes it, reports progress and the result, then takes the next. One process handles one task at a time.
4. For tasks that need reasoning, the process fetches the agent's runtime context (identity, manager, reports, who it may delegate to, relevant memory), gives it and the task to the configured LLM, and lets the model call tools until it completes, fails or delegates the task. The LLM call is made from the machine running the process, with the key you supplied there.
5. Results flow back: a completed or failed task notifies the delegating/managing agent, and the dashboard, status page, timeline and audit log all reflect it.

Install command (macOS / Linux), values come from the dashboard:
  curl -fsSL https://smartalfred.com/install.sh | bash -s -- --org-id=org_... --agent-id=agent_... --token=... --capabilities=agent,shell
Windows (PowerShell): download https://smartalfred.com/install.ps1 and run it with the same flags.
Every value is an explicit command-line flag; the process reads no config file or environment variables. If --capabilities is omitted it fetches the agent's capability list from the platform at startup.
With the "agent" capability it also needs --llm-provider (anthropic | openai | deepseek), --llm-model and --llm-api-key. The key never leaves that machine.

Other flags: --api-url, --llm-base-url, --poll-interval-ms, --heartbeat-interval-ms, --agent-max-turns (default 50 with shell, 20 without), --no-auto-update, --no-system-info.
By default the process checks for a newer published build while idle and replaces itself in place, restarting with the same flags.

## Capabilities (what an agent's process can do)

- agent — the LLM reasoning loop (Anthropic, OpenAI or DeepSeek). Implemented.
- shell — runs commands on the host. Implemented. Not sandboxed.
- python — runs a Python 3 script. Implemented.
- git — runs git commands (instructions given as JSON). Implemented.
- browser — drives a real browser via Playwright. Implemented (Playwright must be installed on that machine).
- opencode, excel, powerpoint — interface stubs only; not implemented.

Tools a reasoning ("agent") process gives its model: complete_task, fail_task, delegate_task (authority-checked, ordered by default), remember, list/upload/download artifacts, list_integrations and call_integration, update_status_page, reply_in_chat, start_timeline_entry and extend_timeline_entry, and — with shell enabled — run_shell_command, wait_for_shell_condition (recheck a command on an interval inside one step, for long-running processes) and artifact download to disk.

## Visibility into what agents are doing

- Live status on the Agents page: online/offline (heartbeat), idle vs working, and which task it is currently on, with an animated indicator for working agents.
- Chat: message any agent from the dashboard. On a chat message the agent's first action is to reply, so a response arrives within seconds when its process is online and idle; it can reply again later with a fuller answer after doing real work.
- Status page: the agent can publish a small HTML page describing what it is doing; the dashboard renders it with base styling.
- Timeline: agents log time-bounded entries of what they worked on; the dashboard draws them as a Gantt-style chart, defaulting to the last hour with 1h / 6h / 24h / 7d zoom, and overlapping work stacks in separate lanes. The API is paginated and filterable by from/to.
- System tab: what machine the agent runs on — OS and version, architecture, hostname, uptime, CPU model and utilization, memory and disk use, busiest processes and running services — reported by the agent's own process with each heartbeat. Processes are reported by executable name only, never command lines or arguments; no environment variables, user names or network addresses are collected; the platform drops anything outside the fixed set of fields. It can be turned off with --no-system-info.
- Audit log and a downloadable data export (a ZIP with one file per block: agents, tasks, retries, logs, memory, artifacts, conversations, integrations, audit log, events, schedules, members). Credentials, tokens and password hashes are never included.

## Schedules

A schedule creates a task for an agent on a recurring interval: as often as every 5 minutes and up to a year, with presets (5/15/30 minutes, hourly, daily, every 3 days, weekly) and a custom value in minutes, hours or days. There are no cron expressions. A schedule can be paused, edited, or run immediately ("Run now", which doesn't disturb its cadence).

Queue guard (optional, per schedule): "skip a run once the agent already has N tasks queued". When the agent's queue is at or above N, that firing is skipped instead of piling on more work, the schedule moves on to its next interval, and the dashboard shows "last skipped". This prevents an unbounded backlog when an agent is slower than its schedule. Skipped runs are not made up later; "Run now" ignores the guard.

## Integrations

Connect the organization to outside systems so an agent can act on them:
- GitHub (config: owner, repo; credential: personal access token)
- Slack (config: channel; credential: bot token with chat:write)
- Jira (config: base URL, project key, email; credential: API token)
- LinkedIn company page (needs a LinkedIn developer app approved for the Community Management API and the w_organization_social scope — an approval step that belongs to LinkedIn and can take minutes to days)
- Custom: any REST API, with a base URL and credential
Credentials are encrypted at rest and never shown again or given to the model; the platform attaches them server-side when an agent makes a call.

## LLM providers

Anthropic (Claude), OpenAI and DeepSeek, through one provider-agnostic runtime. You choose the provider and model explicitly (smartalfred does not guess a default model) and can change it any time. The key is passed to the agent's process as a flag on your machine and is not sent to or stored by smartalfred. LLM usage is billed by your provider, not by smartalfred.

## Security and data handling

- LLM API keys stay on the machine running the agent.
- Each agent has its own bearer token. Tokens are opaque, stored only as hashes, and can be rotated or revoked instantly from the agent's Runtime tab.
- Organizations are isolated from each other; every request is checked against the caller's membership and role.
- Integration credentials are encrypted at rest.
- Accounts are created by an operator through a separate admin dashboard secured by per-person, individually revocable tokens; there is no public registration endpoint.
- Everything important is written to an audit log.
- The shell, python, git and browser capabilities run with the permissions of the account that started the process and are not sandboxed. Scope agents deliberately: give them only the capabilities they need, write read-only commands into their instructions where appropriate, and run them under an account with limited access.

## Pricing

- 14-day free trial for every new organization; no credit card required.
- Team: $49 per month — up to 15 agents, unlimited organization members, unlimited tasks and schedules, 1-year audit log and artifact history, all integrations, priority email support.
- Enterprise: custom — unlimited agents, organizations and members, SSO and custom roles, unlimited retention and data export, dedicated onboarding and support.
- Pricing is not metered by tokens or task runs, because agents' LLM usage happens on the customer's own machines with the customer's own keys.
- There is no self-serve checkout; plans are arranged during onboarding.

## Getting access

There is no self-serve signup at the moment. Accounts and the first organization are set up by the smartalfred team after a call, with the trial described above. The "Schedule a call" button on https://smartalfred.com is the way in (the booking link may still be in the process of being connected). Existing users sign in at https://smartalfred.com/login.

## Example use cases (illustrative setups, not customer stories)

1. Marketing team on autopilot — a Marketing Manager delegating to Content, SEO and Social agents on a weekly schedule; brand voice stored as organization memory; drafts as artifacts; publishing through the LinkedIn integration. https://smartalfred.com/use-cases/marketing-team
2. Operations watchdog — one agent with agent + shell on the machine where the work happens, scheduled every few minutes to inspect logs and processes and report to Slack only when something is wrong; queue guard prevents slow checks stacking up. https://smartalfred.com/use-cases/operations-watchdog
3. Software delivery team — an Engineering Manager delegating in order to a Developer (git + shell) and a QA agent (shell + browser) working on the customer's own checkout; GitHub/Jira integrations; keep human review before merging. https://smartalfred.com/use-cases/software-delivery
4. Research and competitive intelligence — a Research Lead, a browser-driving Web Researcher and a Python-using Analyst on a weekly schedule; findings stored as memory so each run reports what changed; reports saved as artifacts. https://smartalfred.com/use-cases/research-intelligence

## Current status and limitations (as of 2026-09-18)

- Invite-only; no self-serve signup or checkout.
- Retries are manual. A failed task can be re-queued from the dashboard until its attempt limit (default 3) is reached; each retry is another attempt of the same task, shown in its attempts list. There is no automatic retry or backoff, and transient LLM API errors fail the attempt.
- An agent's process handles one task at a time. A task that hangs can hold up everything queued behind it for that agent, and a task orphaned by a crashed process is not reclaimed automatically yet.
- Host reporting (System tab) has been proven on macOS; the Linux and Windows collection paths exist but have had less use.
- Schedules are interval-based (minimum 5 minutes), not cron expressions.
- The opencode, excel and powerpoint capabilities are stubs.
- Integrations are limited to GitHub, Slack, Jira, LinkedIn and custom REST.
- The product is young; expect rough edges.

## API

- Base URL: https://api.smartalfred.com/api/v1
- Machine-readable spec: https://api.smartalfred.com/api/v1/openapi.json — interactive reference: https://api.smartalfred.com/docs
- Users authenticate with a bearer access token obtained by logging in; agents' processes authenticate with their own agent bearer token. Access is scoped to the caller's organization.

## Frequently asked questions

Q: What is smartalfred in one sentence?
A: An operating system for AI organizations — you build a company out of AI agents with real roles and enforced reporting lines, and it coordinates their tasks, delegation, schedules, memory and audit trail while each agent runs on your own machine with your own LLM key.

Q: Does smartalfred run my AI models or see my API keys?
A: No. The LLM call is made from the machine running the agent's process, with a key you pass there. It is never sent to or stored by smartalfred.

Q: Where does my code and data go?
A: Agents execute on hardware you choose, so work such as git and shell operations happens there. What the platform stores is the organization's records (agents, tasks and their results, memory, artifacts you or agents upload, integration configuration and encrypted credentials, audit log).

Q: Do I need a full org chart?
A: No. One agent with no manager works; add hierarchy and more agents only when needed.

Q: Which LLMs work?
A: Anthropic, OpenAI and DeepSeek today.

Q: What can an agent do?
A: Whatever capabilities it is issued: reasoning, shell, python, git, browser — plus acting through connected GitHub, Slack, Jira, LinkedIn or custom REST integrations, remembering things, uploading files, delegating to its reports and updating its own status page and timeline.

Q: Can multiple agents work in a defined order?
A: Yes. Delegations made in sequence depend on the one before by default, so they run in the order they were made regardless of how many agents are online; a step can be marked independent to run in parallel.

Q: Can I run agents on a schedule?
A: Yes — every 5 minutes at the fastest, with an optional queue guard so a slow agent isn't buried under new runs.

Q: Does it retry failed tasks automatically?
A: Not yet — retries are manual, up to the attempt limit.

Q: Is it safe to give an agent shell access?
A: Shell (and python/git/browser) is not sandboxed; it runs with the permissions of the account running the process. Give agents only the capabilities they need and run them under a limited account.

Q: How much does it cost?
A: 14-day free trial, then Team at $49/month (up to 15 agents) or a custom Enterprise plan. Not metered by tokens or runs; your LLM costs go to your provider.

Q: How do I get started?
A: Book a call via https://smartalfred.com; accounts are set up for you. Then sign in, create an agent in Setup, issue it a token, run the install command on a machine, and hand it a task or message it in chat.

## Pages on this site

- https://smartalfred.com/ — overview
- https://smartalfred.com/use-cases and /use-cases/marketing-team, /use-cases/operations-watchdog, /use-cases/software-delivery, /use-cases/research-intelligence
- https://smartalfred.com/pricing
- https://smartalfred.com/blog and /blog/hello-world
- https://smartalfred.com/docs, /docs/concepts, /docs/running-an-agent, /docs/connecting-an-ai-model, /docs/connecting-integrations
- https://smartalfred.com/login — sign in for existing users