Skip to content

manage-capabilities.mdx

Latest commit

 

History

History
175 lines (128 loc) · 8.11 KB

manage-capabilities.mdx

File metadata and controls

175 lines (128 loc) · 8.11 KB
title Manage Capabilities
description Step-by-step guide to creating, editing, and managing capabilities in the Torus control space.

import { Steps, Aside, CardGrid, Card } from "@astrojs/starlight/components";

import ClickableImage from '/src/components/ClickableImage.astro'; import RedText from '/src/components/RedText.astro'; import confirmCapability from '/public/images/how-to-guide/manage-capabilities/create-capability-confirm-information.png'; import deleteCapability from '/public/images/how-to-guide/manage-capabilities/delete-capability-confirm-information.png';

In this guide, we'll walk through managing capabilities in the Torus control space.
Capabilities allow you to integrate off-chain resources and services with Torus's on-chain permission system.

Why Manage Your Capabilities?

Managing capabilities means taking deliberate control over what your agent can do — and what others can do on its behalf.
By creating capability paths, you define the exact functions your agent exposes, enabling collaboration through delegated permissions.
By removing outdated or unused capabilities, you reduce the attack surface and keep your agent’s scope minimal and secure.

What we will accomplish

⏱️ **Estimated time to complete this guide: 10 minutes**

Prerequisites

You must have a registered agent on Torus. Follow the [agent registration guide](https://docs.torus.network/how-to-guides/builders/register-an-agent/) if needed. Ensure you have enough TORUS to cover capability registration and deposit fees.

Register a Capability path

  1. Visit the Create Capability Tab in the Torus Portal
    Navigate to the Capabilities section in the Torus Portal.

  2. Connect your Torus Wallet
    Ensure you're connected with the agent account that will own the capability.

  3. Select the Capability Prefix and Create your Capability Path
    Your capability will follow this structure:
    agent-name.capability-path.METHOD

    • The agent-name is your registered agent name (pre-filled and uneditable).
    • The capability-path is the custom route you define (e.g. tokens, profile_data, etc.).
    Capability paths can only contain **lowercase letters**, **numbers**, **hyphens**, and **underscores**. You **do not** need to type the agent name or method — they are handled by the UI.

    Maximum Depth: 10 segments total

    • agent. counts as 1 segment
    • agent-name counts as 1 segment
    • You can create up to 8 additional capability segments

    Examples:

    • example-agent.tokens.[method] ✅
    • example-agent.profile_data.[method] ✅
    • example-agent.claim.rewards.[method] ✅ Valid (multiple dots are fine within the full structure)
    • example-agent.tokens-.[method] ❌ (Invalid. Hyphen at the end of capability path)
    • example-agent.Tokens.[method] ❌ (Invalid. Uppercase letter in capability path)
    • example-agent.tokens!.[method] ❌ (Invalid. Special character ! not allowed)
    • example-agent tokens[method] ❌ (Invalid. Space in capability path)

  4. Select REST Method
    The METHOD is the REST method you select from the list: (GET, POST, PATCH, DELETE, PUT, CUSTOM, NONE).

    - **GET** — Retrieve data (e.g. fetch a profile or list). - **POST** — Create new data (e.g. submit a form). - **PATCH** — Update part of an existing resource (e.g. change a name). - **PUT** — Replace a resource entirely. - **DELETE** — Remove a resource. - **CUSTOM** — Define your own method name (useful for RPC-style or special actions). - **NONE** — Leave this field blank (if your capability doesn’t involve a method call).

  5. Review information, Submit and Sign the Transaction
    Review the capability path in the Full Capability Path field.
    If everything is correct, click Create Capability.
    Open the SubWallet extension and sign the transaction.

  6. All Done
    You've now successfully created a capability on the Torus control space. Now you can delegate permissions to it.

Delete a Capability path

  1. Visit the Delete Capability Tab in the Torus Portal
    Navigate to the Capabilities section in the Portal.

  2. Connect your Torus Wallet
    Ensure you're connected with the agent account that owns the capability you want to delete.

  3. Select the Capability Segment to Delete
    From the dropdown menu, choose the capability segment you want to remove from your agent.

    Capabilities are structured in segments like:
    agent.your-agent-name.test-path.get.depth.add.delete

    **Understanding Segment-Based Deletion**

    You can delete capabilities by segments, and deletion always removes all subsequent segments:

    Examples:

    • Delete .get → Removes .get.depth.add.delete
    • Delete .add → Removes .add.delete (but keeps .get.depth)
    • Delete .test-path → Removes .test-path.get.depth.add.delete

    In the Delegation Preview, green segments will remain and red segments will be deleted.

    **Deleting a capability segment is permanent and cannot be undone.**

    Once deleted, any permissions or integrations relying on the deleted segments will stop working immediately. Make sure you're certain about removing these capability segments before proceeding.

  4. Review information, Submit and Sign the Transaction
    Review the capability path you're about to delete in the preview field.
    If you're certain you want to proceed, click Delete Capability.
    Open the SubWallet extension and sign the transaction.

  5. All Done
    You've successfully deleted the capability from the Torus control space. Any existing permissions or delegations to this capability are now invalid.

What's Next?

Now that you can manage capabilities, you might want to:

  • Set up delegation: Manage permissions to allow other agents to use your capabilities
  • Build agent services: Create an agent server to provide APIs that utilize your registered capabilities
  • Create demand signals: Signal for specific capabilities you need from other agents

Connect with the community:

  • Discord — Technical discussions, support, and announcements
  • Telegram — General chat and announcements
  • Twitter — Updates and ecosystem news
Learn about [recursive delegation](https://docs.torus.network/explanations/system/recursive-delegation/) delegation mechanisms and control space architecture.