Smith (Agent Smith)

Smith Fleet Management

Smith is an open-source fleet management system built in Rust for managing distributed IoT devices at scale. Born from managing thousands of devices across healthcare facilities, Smith provides the automation and reliability you need to deploy, monitor, and update your fleet with confidence.

Why Smith?

Built for Scale: Manage everything from hundreds to thousands of devices
Reliable: Designed for >99% uptime in critical environments
Seamless Updates: Deploy upgrades and rollbacks with zero manual intervention
Transparent: Open-source infrastructure you can trust and extend

Architecture

Smith consists of five main components:

smithd: Daemon that runs on each device to execute deployments and report status
updater: Daemon that keeps smithd up to date
api: Backend service managing deployment configurations and fleet status
dashboard: Visual interface to monitor your fleet in real-time
cli (sm): Command-line tool for fleet administrators

Getting Started

Visit our documentation to get started with Smith.

Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes Smith better for everyone. Check out our issues or submit a PR.

Security

Security is a top priority for Smith. If you discover a security vulnerability, please email security@teton.ai. We operate a bug bounty program and have paid bounties for responsibly disclosed vulnerabilities. See our Security Policy for more details.

License

The Smith source and documentation are released under the Apache License 2.0

Getting Started

Installing the Smith CLI (Command Line Interface)

Download and install

Let's install sm the Smith CLI (Command Line Interface) on your system using the terminal commands below.

curl -fsSL https://docs.smith.teton.ai/install.sh | sh

Testing your installation

After installing the sm CLI, you can test your installation by running the following command:

sm --version

Use sm help to see help text documenting Smith's flags and usage.

Getting Started

Follow this guide to get started with local development.

Setup

First, you will need the following stuff installed/setup:

Docker
1password
node

Then run make init. This will initialize the repo with all the stuff you need. At the time of writing this will

Create .env files (.env and dashboard/.env) for you. Please fill in the missing values

Starting the api

Run make up, then make migrate and finally make dev to start the api.

Try running

curl http://localhost:8080/health

to check that it's running as it should. It should return something like

I'm good: <version number>

Starting the dashboard

Run the following

cd dashboard
npm i
npm run dev

The dashboard should now be running on localhost:3000

Starting smithd

Just run make run, which will start smithd and create a magic.toml for you.

You can now open the dashboard, and see a device in the "Pending Approval" box. Press approve, and you should be golden.

Starting the CLI

Run

cargo run --bin sm

You probably need to run it some times initially since it needs to create some defaults. If it shows a list of commands, you are golden.

CLI Overview

Command line tool (sm)

Smith provides a command line tool for communicating with the Smith API to manage your fleet of devices.

This tool is named sm.

For configuration, sm looks for configuration files in the $HOME/.config/smith directory. You can manage multiple profiles and switch between them using the sm profile command.

This overview covers sm syntax, describes the command operations, and provides common examples. For details about each command, see the individual command reference pages.

Installation

See the Installation Guide for installation instructions.

Syntax

Use the following syntax to run sm commands from your terminal window:

sm [command] [TYPE] [NAME] [flags]

where command, TYPE, NAME, and flags are:

command: Specifies the operation that you want to perform on one or more resources, for example get, status, restart, logs.
TYPE: Specifies the resource type. Resource types support aliases and you can specify the full name or abbreviated forms. For example, the following commands produce the same output:
```
sm get device ABC123
sm get devices ABC123
sm get d ABC123
```
NAME: Specifies the name of the resource (device serial number or ID). Names are case-sensitive. If the name is omitted, details for all resources are displayed, for example sm get device.

When performing an operation on multiple resources, you can specify each resource by name or use filters:
- To specify multiple resources by name:
```
sm get device ABC123 XYZ789 DEF456
```
- To filter resources by labels:
```
sm get device --label env=production --label region=us-west
sm get device -l env=production -l region=us-west
```
- To filter resources by status:
```
sm get device --online
sm get device --offline
```
- To search with partial matching:
```
sm get device rpi nano --search
sm get device rpi -s
```
flags: Specifies optional flags. For example, you can use the --json flag to output results in JSON format, or --nowait to queue commands asynchronously.

Common Resource Type Aliases

Resource Type	Aliases	Example
`device`	`devices`, `d`	`sm get d --online`
`service`	`services`, `svc`	`sm status svc nginx ABC123`
`commands`	`cmds`	`sm get cmds ABC123`

Device Selection

Most commands support flexible device selection through a common set of flags:

Positional IDs: Specify one or more device serial numbers or IDs
--label KEY=VALUE (-l): Filter by labels (can be used multiple times)
--online: Show only online devices (last seen < 5 minutes)
--offline: Show only offline devices (last seen >= 5 minutes)
--search (-s): Enable partial matching for device IDs (matches serial number, hostname, or model)

Examples

# Single device by serial number
sm get d ABC123

# Multiple devices
sm get d ABC123 XYZ789

# All devices with a label
sm get d -l env=production

# Search for devices (partial match)
sm get d rpi -s

# Multiple search terms
sm get d rpi nano -s

# Combine filters
sm get d -l env=staging --online

Authentication

Before using the CLI, you need to authenticate:

sm auth login

This will open your browser for authentication. Use --no-open to prevent automatic browser launch.

To logout:

sm auth logout

To view your current token:

sm auth show

Common Workflows

Checking device status

# List all devices
sm get d

# Check which devices are online
sm get d --online

# Check smithd status on a device
sm status d ABC123

# Check if updates are available
sm status d -l env=production

Troubleshooting

# Get device logs
sm logs ABC123

# Check service status
sm status svc smithd ABC123

# Restart a service
sm restart svc smithd ABC123

# Test network connectivity
sm test-network ABC123

# Run custom diagnostic command
sm run ABC123 -w -- dmesg | tail -n 50

Managing labels

# Add environment label
sm label ABC123 env=production

# Query by label
sm get d -l env=production

# Update multiple devices
sm label -s rpi region=warehouse-1

Tips

Use aliases to save typing: sm get d instead of sm get device, sm status svc instead of sm status service
Use short flags where available: -l for --label, -s for --search, -j for --json, -o for --output
Use --search (-s) flag for fuzzy matching when you don't remember the full serial number
Combine multiple labels to narrow down device selection: sm get d -l env=prod -l region=us
Use --nowait for bulk operations to queue commands asynchronously
Use sm get cmds to check the history of commands sent to a device
Most commands support --json (-j) flag for machine-readable output
Use sm agent-help to get a comprehensive markdown reference for automation

Command Reference

get - Retrieve information about resources
status - Get status information for devices or services
restart - Restart devices or services
logs - Get logs from devices
run - Run custom commands on devices
label - Set labels on devices
Other Commands - Additional utility commands

get

The get command retrieves information about resources in your fleet. Use it to inspect device details, view command history, and filter resources by various criteria.

Available Resources:

device (alias: d, devices) - View device information and metadata
commands (alias: cmds) - View command history for devices

Quick Examples

# List all devices
sm get d

# Get a specific device
sm get d ABC123

# Get only online devices
sm get d --online

# Search for devices by partial match
sm get d rpi -s

# View command history for a device
sm get cmds ABC123

# Filter devices by label
sm get d -l env=production

get device

Display information about one or more devices in your fleet. Without any arguments, lists all devices.

Smith Documentation