§ guide · operators

Getting started

The shortest path from a fresh Powerloom workspace to a governed agent in production. Twenty minutes if you already have an Anthropic API key. Thirty if you need to set one up.

This guide covers the cloud edition. For self-hosted, see Powerloom Home.

What you need

An email you control (Google, Microsoft, or GitHub for SSO; otherwise email + password).
An Anthropic API key. Sign up at console.anthropic.com if you don't have one.
A terminal with pip install working, if you want to drive Powerloom from the CLI.

That's the full prerequisite list. No AWS account, no Docker, no Terraform on your machine. The Powerloom control plane runs on our infrastructure; you talk to it.

Step 1 — Create your workspace

Go to app.powerloom.org and request access. Powerloom is invite-only during the closed beta; the request form takes about a minute.

Once your invite lands, click through, pick an SSO provider, and confirm your organization name. The signup flow asks three short questions about how you'll use Powerloom — this is what Alfred (your meta-agent) reads as context for your first conversation. Optional, skippable.

When the workspace boots, you land on /overview. Three things are already in place:

Your organization, with you as OrgAdmin at the root OU.
Your root organizational unit (named after your org slug, e.g., acme/).
Alfred, the meta-agent. He's provisioned but not invocable yet — he needs your Anthropic key to make API calls.

Step 2 — Add your Anthropic key

Open /settings/credentials. Pick Anthropic from the provider list and paste your key. Powerloom encrypts it with AES-256-GCM under your tenant's KMS customer master key. The raw key never leaves the request body; it lives only as a wrapped ciphertext on disk.

You'll see a green "verified" check once Anthropic accepts the test call. Alfred is now invocable.

If you want to add OpenAI, Bedrock, or another provider later, the same /settings/credentials page is the place. One key per provider per scope.

Step 3 — Model your first OU

Powerloom mirrors your org chart as a tree of organizational units. The root OU (your org slug) is already there. Add a child for the team that's going to run agents first.

From the CLI:

pip install loomcli
weave login app.powerloom.org
weave apply -f - <<'YAML'
apiVersion: powerloom/v1
kind: OU
metadata:
  name: engineering
  parent_ou_path: /acme
  display_name: Engineering
  description: All engineering teams
YAML

From the console: /organization → right-click the root OU → New → Organizational Unit. The form does the same thing.

The OU shows up in /organization immediately. Every agent, MCP deployment, role binding, and credential you create from here on lives inside an OU.

Step 4 — Bind a role

You're already OrgAdmin at the root, which means you can do anything anywhere. For real production use you want narrower scopes — bind OUAdmin to a teammate at the OU they actually run.

apiVersion: powerloom/v1
kind: RoleBinding
metadata:
  principal_ref: user:alice@acme.com
  role: OUAdmin
  scope_ou_path: /acme/engineering
  decision_type: allow

weave apply -f rb-alice.yaml. Alice now has admin authority over /acme/engineering and everything below it. She can create agents, attach skills, and manage MCP deployments inside that scope. She cannot touch /acme/accounting, because no binding grants her access there.

To deny access explicitly — say, a contractor group should not see the production agent — write a decision_type: deny binding. Deny always wins at the same scope.

The full RBAC reference is at /docs/rbac.

Step 5 — Deploy an agent

Now the payoff. Declare an agent, attach a skill or MCP server, apply.

apiVersion: powerloom/v1
kind: Agent
metadata:
  name: code-reviewer
  scope_ou_path: /acme/engineering
  display_name: Code reviewer
  description: Reviews pull requests for the platform team
  model: claude-sonnet-4-6
  system_prompt: |
    You review pull requests for the platform team. Suggest changes
    inline. Approve when the PR is ready. Be terse.

weave apply -f agent-reviewer.yaml. The reconciler picks the agent up within seconds, calls Anthropic to register it as a Claude Managed Agent, and binds your encrypted credential. The status flips from pending to synced when the round-trip succeeds.

The agent now has an identity (agent:/acme/engineering/code-reviewer), a scope (the engineering OU and below), and an audit trail (every invocation lands in the hash-chained log). It can be invoked from /agents/<id>/chat in the console, from weave invoke, or from your own application via the REST API.

What you have now

A workspace, an OU tree, a role binding, and a deployed agent.
An audit trail that records every state-changing action you took to get here.
A meta-agent (Alfred) you can ask to make further changes for you in plain English.

From here, four directions:

Add more agents. Same shape — declare, apply, scope by OU.
Wire MCP servers. /docs/mcp-deployment covers the templates.
Set up approval gates. High-risk actions (creating an OU, attaching a tool to an agent in production) can require a second approver. /docs/auth-and-audit covers the policy syntax.
Build a workflow. Multi-agent handoffs, declared as a DAG. /docs/workflows covers the node kinds.

What if I get stuck

weave plan -f <file> shows what apply would do without doing it. Always safe to run.

weave describe <kind>/<name> shows the live state of any resource — useful when reconciler status is stuck on pending for longer than you'd expect.

/audit shows every action taken in your org, hash-chained. If something happened and you want to know who did it, the answer is there.

For anything that isn't covered, ask Alfred (/agents/alfred-meta/chat) or email support@powerloom.tech.

View raw markdown ↗ · or visit /llms.txt for the docs index