SwayOS usage and development guide

Create and verify an account first, then choose the package matching your operating system and CPU architecture. Protected packages require you to sign in.

1. 1 / ACCOUNT

   Create an account

   Register with an email you can access and complete email verification.

   Register →
2. 2 / PACKAGE

   Choose a package

   Confirm the OS, architecture, and version. Prefer the latest stable desktop build.

   View downloads →
3. 3 / VERIFY

   Launch and sign in

   Open the client and sign in with the same account. Available services load on first launch.

First run

Complete first-time setup

Confirm your account, devices, and data path in this order. Applications and agents will then have a clear place to run.

Fundamentals

Account and authentication

The portal account controls downloads and public services; a node account controls resources in a SwayOS environment. Credentials may be issued by different services. Never commit tokens to source control.

Core workflow

Connect and manage devices

GMeta holds control-plane data such as devices, accounts, and schedules. XAgent runs on the device and performs file, runtime, and system operations. A listed device is not necessarily online.

Agents

From marketplace to runtime

Review an agent's purpose, author, and version here. To install it, open your Sway cluster and use the App Marketplace inside the cluster. Agents that execute tasks also need an online device and an available runtime.

1. 1

   Review

   Check description, version, permissions, and dependencies.

2. 2

   Install in cluster

   Open your Sway cluster and install from its App Marketplace.

3. 3

   Schedule

   Bind a device and runtime, then monitor status and logs.

Developer tools

Use the Sway CLI

The CLI is suited to diagnostics, batch queries, and automation. The binary in this repository is named sway-cli and can be installed from source.

git -C app/sway-sdk submodule update --init sway-cli
cd app/sway-sdk/sway-cli
cargo install --path . --locked
sway-cli --help

sway-cli config init
sway-cli config set gmeta_url https://<your-gmeta-host>
sway-cli auth login --username <name> --password '<password>'
sway-cli health --detailed

# List online devices as JSON
sway-cli device list --status online --format json

# Inspect the current local configuration
sway-cli config show --format human

Tip: a password argument can be recorded in shell history. On shared machines, use a temporary session and run sway-cli auth logout when finished.

Application integration

JavaScript / TypeScript SDK

@sway/sdk exposes device, user, application, data source, task, and cluster clients through one entry point. Inject service URLs and tokens from the deployment environment.

import { JsSwayClient } from '@sway/sdk';

const client = JsSwayClient.new({
  gmeta_url: 'https://<your-gmeta-host>',
  auth_token: process.env.SWAY_AUTH_TOKEN,
  timeout_ms: 30_000,
});

const health = await client.healthCheck();
const devices = await client.device().listDevices();

console.log(health.status, devices.items);

Configuration reference

Common environment variables

Automation can override local configuration with environment variables. Secret values should come from CI/CD secret storage, not example .env files or the repository.

Troubleshooting

Common issues