eaststarai/sanad-agent

A local-first, cross-platform AI agent for your computers and servers—all managed from one interface.

Sanad Agent runs a native Dart agent close to your files and tools. Use it locally with offline models, or install it on multiple computers and headless servers and manage them from the same Flutter client on desktop, mobile, or the web.

Sanad Agent is created by Ahmed Attia and developed under EastStar AI, an independent AI studio.

One Sanad experience across desktop and mobile.

Why Sanad

Explore the complete capability set and its current boundaries in Sanad Agent Features.

Quick start

Using an AI agent? Share the Install Sanad skill with it so it can inspect your machine, explain the release-user and source-developer paths, and safely carry out the path you choose. Then let Sanad handle the rest.

For users

Download Sanad Client

1. Download and launch Sanad Client for your desktop platform.
2. Choose Run Locally. The Client downloads, verifies, installs, and starts the matching Sanad Agent automatically; you do not download Agent separately.
3. Add a local or hosted model provider, select a workspace, and start working.

A Sanad account and pairing token are not required for this local-only path. On mobile, use the Web Client until stable Android and iOS apps are publicly available.

Unsigned Windows build: The current Windows release is unsigned. Download it only through the official button above and follow the verification guidance in Install and Use Sanad Agent.

Connect another computer or a server

Only Sanad Agent needs to be installed on the remote machine. Keep using Sanad Client on your desktop, phone, or the web.

1. Open Sanad Client on desktop, mobile, or the web.
2. Open Device Management, choose Add device, and name the device.
3. Copy the complete command generated by the Client and run it once on the target computer or headless server.
4. Return to the Client, select the connected device, and begin working with its workspaces and conversations.

The generated command contains a short-lived, creation-only pairing credential. Do not construct, paste, or share that credential separately. On the first successful connection, the Agent replaces it with a durable device credential generated locally.

Alternatively, install the Agent directly, then choose account sign-in or local-only mode. For macOS or Linux:

curl -fsSL https://sanad.eaststarai.com/install.sh | bash

For Windows PowerShell:

irm https://sanad.eaststarai.com/install.ps1 | iex

Choose account sign-in to connect the machine through the Portal, or skip it to run the Agent locally and connect later. The installer never blocks an unattended terminal waiting for an answer.

Unsigned Windows build: The 1.0.1 Windows installer is intentionally unsigned. Verify that it came from the official release and that its SHA-256 matches the published release manifest before proceeding. Do not disable Microsoft Defender or Smart App Control. Windows release gates run on Windows 11; Windows 10 has not been validated.

See Install and Use Sanad Agent for client packages, explicit installer modes, manual installation, service management, providers, updates, and removal.

For developers

Prerequisites: Ensure your system has the build toolchain for your platform:

• Windows: Visual Studio 2022 with Desktop development with C++.
• macOS: Xcode Command Line Tools (xcode-select --install).
• Linux: clang, cmake, ninja-build, pkg-config, libgtk-3-dev, lld.

See the Developer Guide for full prerequisites and details.

Clone the repository and enter its directory:

git clone https://github.com/EastStarAI/sanad-agent.git sanad-agent
cd sanad-agent

Install the user-scoped development command once. On macOS or Linux:

scripts/sanad-dev install

On Windows PowerShell:

.\scripts\sanad-dev.ps1 install

Then use the official source run command on every platform:

sanad-dev run

run installs any missing pinned tools, resolves the shared Release Contract, Agent, and Client dependencies when stale, then starts the complete managed pair. Installation and setup stream their real process output and require no administrator access.

This source-development path is independent from the release installer above and does not require a pairing token.

For Flutter device selection, local-only operation, development commands, and testing workflows, follow the Developer Guide.

Choose how you work

Command Line Interface (CLI)

Sanad includes a full-featured terminal interface and interactive REPL that communicates with the local agent daemon or runs standalone.

Interactive Chat (REPL)

Start an interactive reasoning session right in your terminal:

sanad
# or
sanad chat --model claude-3-7-sonnet --thinking

Inside the REPL, manage sessions and inspect tools with interactive slash commands:

• /ws or /workspace: View active workspace, list (/ws list), or switch (/ws switch ).
• /model: Inspect active model or switch (/model switch ).
• /steer : Steer an active agent run mid-flight without aborting.
• /stop: Interrupt an active turn cleanly (Ctrl+C also supported).
• /compact: Trigger context compaction for long-running sessions.
• /skills & /mcp: Inspect installed skills and connected MCP servers.
• /help: Display REPL shortcut reference.

One-Shot Tasks & Unix Pipes

Execute one-shot tasks directly without entering interactive chat:

# Execute prompt directly
sanad -p "Explain the difference between TCP and UDP"
# or
sanad run "Find all TODO comments in lib/"

# Pipe input from stdin into Sanad
cat server.log | sanad run "Identify any connection timeouts"

# Output structured JSON for automation and scripts
sanad run "Count lines of code in src" --json

# Quiet mode: suppress banners and output only final assistant text
sanad run "Generate a random UUID" --quiet

# Run in-process without a daemon, with a bounded deadline
sanad run --standalone --timeout 300 "Review this workspace"

# Dangerous and invocation-scoped: auto-approve every gated tool
sanad run --standalone --allow-all-tools "Run the trusted maintenance script"

Standalone and daemon modes share the same engine and exclusive state-root ownership. A standalone invocation refuses to open SQLite when another runtime owns the selected Sanad Home. Timeout, SIGINT, and SIGTERM return 124, 130, and 143; --json reserves stdout for one result object.

Workspace Management

Auto-discover and manage project workspaces from the command line:

sanad ws list                          # List registered workspaces with security policy
sanad ws current                       # Show active workspace, path, and connected MCP servers
sanad ws switch               # Switch the active workspace
sanad ws add [path]                    # Register existing folder as workspace (defaults to .)
sanad ws create                  # Create a new folder and register as workspace
sanad ws tree                          # View hierarchical directory tree of active workspace
sanad ws policy [default|full_access]  # View or toggle security permission mode

Diagnostics & Inspection

sanad doctor                           # Inspect environment health, Sanad Home, and daemon connectivity
sanad models                           # List available and configured AI models
sanad providers                        # Inspect supported AI providers

How it works

Flutter Client
├── Direct local connection ─────────► Dart Agent on this computer
└── Optional hosted connection ──────► Sanad Gateway ─────► Dart Agent on a remote device

Dart Agent
├── Workspaces, sessions, recovery, memory, and provider configuration
├── Built-in tools, MCP servers, skills, and permission enforcement
└── Local model or external model-provider connection

The Dart agent owns execution and local state. The Flutter client provides the interface for selecting devices, workspaces, conversations, providers, and models while rendering messages, tools, permissions, questions, queues, and recovery state.

Repository structure

• agent/ — native Dart CLI and background service that owns execution and local state.
• client/ — Flutter interface for local and remote devices.
• docs/ — product, technical, operations, and QA documentation.
• scripts/ — development, documentation, build, and release tooling.

Key interactions

Steer while the agent works

Send a normal message during an active run to redirect it at the next safe boundary without discarding its progress. Use Ctrl+Enter on Windows/Linux or Cmd+Enter on macOS to queue a separate request instead. Queued work can be promoted to steering or removed, and Stop restores unexecuted input to the draft.

Let the agent ask

The agent can suspend a turn and show a question card with suggested answers and a custom-response option. Your answer resumes the same turn. Permission requests use a separate inline card and remain governed by workspace policy.

Use multiple providers and accounts

Create multiple instances of one provider—for example, separate personal and work accounts. Each instance has independent credentials, model, readiness, rate limits, and failover policy. ChatGPT Subscription instances can also show their authoritative Session and Weekly usage windows.

Independent provider resources

Sanad can work with local or hosted providers and multiple accounts for the same provider.

• Free LLM API Resources — a community-maintained directory of LLM services offering free tiers or trial credits.

This is an independent third-party resource and is not affiliated with Sanad. Models, quotas, prices, privacy practices, and usage terms may change; review each provider’s terms before sending workspace data.

Extend it with MCP and skills

Connect MCP servers over stdio, Server-Sent Events, or streamable HTTP, and install skills globally for the user or locally for a workspace. Workspace definitions take priority over user-level capabilities with the same name.

Platforms

Feature status and constraints

• Scheduling: persisted one-shot tasks can run while the agent service remains active. Recurring cron-style schedules are not part of the stable scheduling surface.
• Computer use: desktop screenshot, keyboard, and mouse tools require explicit enablement and the corresponding operating-system permissions.
• Realtime voice: the Gemini Realtime voice path is experimental, hidden by default, and not part of the stable feature set. See Experimental Realtime Voice.
• Capacity: Sanad does not impose a fixed product count on conversations or provider instances; practical capacity depends on the device and the connected providers.

Documentation

Security and privacy

Local workspaces, conversations, provider configuration, memories, and execution state are owned by the agent running on the selected device. Connected-device features exchange the identity, device inventory, commands, and events necessary to operate the remote relay.

Never commit API keys or tokens. Provider credentials and Sanad identity tokens are runtime user data outside Git, and diagnostic serialization redacts credential-shaped fields.

Report vulnerabilities privately according to SECURITY.md.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, follow the nearest AGENTS.md Runtime Contract, and read CODE_OF_CONDUCT.md. Contributions require no CLA or DCO; required checks and protected review labels apply, and human pull requests use squash merge.

Community

• Issues: Report a bug or request actionable work
• Discussions: Propose an idea or ask an architectural question
• Community: Join the Sanad Agent Discord (permanent project invite, lands in #help-and-support).
• Support: Choose the correct help channel
• Governance: Read how decisions and contributions work
• Security: Report vulnerabilities privately
• Code signing: Review artifact trust and signing policy

License

Sanad Agent is available under the MIT License.

Copyright © 2026 Ahmed Attia, operating as EastStar AI.