First Run

A guided walkthrough from a fresh install to your first successful playbook execution.

Tip

Make sure you have completed the Installation and that the app is reachable at http://localhost:3000 before continuing.

Step 1 — Create your admin account

The first user to register on a fresh install automatically becomes the organization admin. Navigate to http://localhost:3000 and click Create account.

You will be asked to choose an organization name. This is your team or company name — it can be changed later in Settings → Organization.

Note

After the first account is created, organization admins can invite additional users from the members settings.

Step 2 — Add an SSH key

Go to Settings → SSH Keys → Add key. You can either paste an existing private key or generate a new key pair directly in the UI.

If you generate a key in the UI, copy the public key shown in the modal and add it to ~/.ssh/authorized_keys on each target server.

Warning

Private keys are encrypted at rest using AES-256-GCM with your ENCRYPTION_KEY. Back up both the key and the encryption key — if either is lost, you cannot recover access.

Step 3 — Add a server

Navigate to Infrastructure → Servers → Add server and fill in:

HostIP address or hostname of the target server
PortSSH port (default: 22)
UserSSH username (e.g. ubuntu, root, deploy)
SSH KeySelect the key you added in Step 2

Click Test connection to verify that SculptOps can reach the server over SSH before saving.

Step 4 — Create an inventory

Go to Infrastructure → Inventories → New inventory. An inventory groups your servers so playbooks know which hosts to target.

Add a group (e.g. webservers), then drag your server into that group. You can add host variables at the group or host level — these are passed directly to Ansible as extra vars.

Step 5 — Write or import a playbook

Go to Playbooks → New playbook. The Monaco-based editor opens with a starter template. For a first test, a simple ping playbook is enough:

---
- name: Ping all hosts
  hosts: all
  gather_facts: false
  tasks:
    - name: Ping
      ansible.builtin.ping:

Save the playbook. A new version is created automatically on each save — you can browse and restore previous versions from the History tab.

Step 6 — Run the playbook

Click Run on the playbook. A dialog appears where you select:

InventoryThe inventory group(s) to target
Extra varsOptional JSON/YAML key-value pairs passed as --extra-vars
Vault passwordOptional — required if the playbook uses encrypted vault variables
Tags / Skip tagsLimit which tasks run (passed as --tags / --skip-tags)

Click Execute. You will be taken to the execution view where real-time output streams as the playbook runs. Lines are color-coded: green for ok, yellow for changed, red for failed.

What happens under the hood

SculptOps spawns a short-lived Docker container using the configured ANSIBLE_DOCKER_IMAGE, mounts your inventory and playbook, and runs ansible-playbook inside it. Output is streamed back to the browser via SSE. The container is removed when execution completes.

Note

All executions are recorded in the audit log. You can view full output, re-run, or download the log from Executions → History.

Configuration

Playbooks