Platform Overview

Platform Hierarchy

Communa is organized in a clear hierarchy:

Workspace (top level)
  └── Project
        └── Agent
              ├── Skills
              ├── Credentials
              ├── Datasets
              ├── Files
              ├── Email
              └── Queue

Everything starts with a Workspace. Inside workspaces, you create Projects. Inside projects, you create Agents. This hierarchy keeps things organized as your AI workforce grows.

Workspaces

A Workspace is your top-level organizational unit — the container for everything. When you sign up, a default workspace is created automatically.

What a Workspace Contains

• Projects — Groups of related agents and skills
• Members — Team members with role-based access
• Billing — Subscription plan and credit balance (billing is per-workspace)

Workspace Members & Roles

You can invite team members to your workspace. Each member has a role that determines their permissions:

Roles are hierarchical — each role inherits the permissions of the roles below it. The Owner has complete control, while Viewers can observe but not modify.

Switching Workspaces

If you belong to multiple workspaces (your own + ones you've been invited to):

1. Look at the bottom of the sidebar for the workspace switcher
2. Click it to see all your workspaces with a search bar
3. Each workspace shows your role — Owner (with a crown icon) or Member (with a people icon)
4. Click a workspace to switch — the app reloads with that workspace's data

The workspace switcher only appears if you have access to more than one workspace. Your last-used workspace is remembered between sessions.

Projects

A Project groups related agents, skills, and data together. Think of projects as departments or workflows:

• A "Marketing" project with content, SEO, and social media agents
• A "Sales" project with prospecting, outreach, and CRM agents
• A "DevOps" project with monitoring, deployment, and incident response agents
• A "Personal" project with your daily assistant, research agent, and email triager

Creating a Project

1. Click New Project on the home dashboard (or use the project switcher → Create New)
2. Enter a name and optional description
3. Click Create — you'll be taken to the project dashboard

What a Project Contains

• Agents — Your AI workers, each with their own sandbox and capabilities
• Skill Catalog — Reusable skills shared across all agents in the project
• Project Dashboard — Analytics, activity feed, and agent status overview
• Settings — Project-level configuration, notifications, API keys, and danger zone

Switching Projects

There are two fast ways to switch between projects:

From the breadcrumbs (fastest):

1. Click the project name in the breadcrumb bar at the top of the page
2. A dropdown appears with search, your project list, and quick actions
3. Click a project to switch, or use View All to go to the home dashboard, or Create New to start a fresh project

From the home dashboard:

1. Click the Communa logo in the top-left corner (always takes you home)
2. You'll see all your projects as cards with mini-dashboards showing agent count, recent runs, and status
3. Click any project card to enter it

Navigation

The Sidebar

The sidebar is your primary navigation within a project:

Below the main navigation, you'll see a live agent list showing every agent in the current project. Each agent displays real-time status:

• 🟢 Green pulse — Agent is currently running
• 🟣 Purple dot — Agent has unread emails or pending queue items (needs attention)
• 🔵 Accent dot — Agent's sandbox is awake (ready but not actively running)
• Schedule indicator — Shows the interval (e.g., "15m") if a schedule is active
• Email counter — Number of unread emails
• Queue counter — Number of pending queue items

Click any agent in the list to jump directly to its detail page.

The sidebar can be collapsed using the chevron button at the bottom, showing only icons for a compact view.

The Top Bar

The top bar contains:

• Communa logo — Click to go to the home dashboard (all projects view)
• Breadcrumbs — Dynamic navigation path showing Project → Section → Detail, with a project switcher dropdown built into the project name
• Profile menu — Your email, credit balance with color-coded status indicator, dark/light mode toggle, and sign out

The credit balance in the profile menu changes color based on your remaining credits:

• Normal — Healthy balance, no indicator
• Amber dot — Low balance warning — time to top up
• Red pulsing dot — Critical balance (near zero) — agent runs may be affected

Clicking the credits item takes you directly to the billing page.

Dashboards

Communa has two dashboard levels that give you visibility at different scopes:

Home Dashboard (All Projects)

Accessed by clicking the Communa logo or navigating to /dashboard. Shows:

• All your projects as cards, each displaying:
  • Project name and description
  • Number of agents
  • Recent run activity as a sparkline chart
  • Quick status indicators
• Overview stats — Total agents and projects across your workspace
• New Project button in the header

If you have no projects yet, a prominent "Launch Your First Agent" empty state guides you through creating your first project and agent.

Project Dashboard

Accessed by clicking Dashboard in the sidebar (or clicking a project card from home). Shows:

• Stat cards — Total agents, agents currently running, run statistics, and credit usage
• Charts — Daily spend, run distribution, and model usage over the last 30 days
• Activity feed — Recent runs and emails across all agents, with timestamps and status
• Top agents — Most active agents ranked by usage, with quick-access links
• Agent filter — Dropdown to filter the entire dashboard to a single agent's data (appears when you have multiple agents)

The project dashboard gives you a command-center view of everything happening in your project at a glance.

Settings

The Settings page (accessible from the project sidebar or profile menu) is organized into sections:

Billing

Billing is managed at the workspace level — meaning the subscription plan and credit balance apply to all projects and agents within a workspace. Access it from the Billing link in the sidebar (it's the same page regardless of which project you're in).

Subscription Status

At the top of the billing page, you'll see your current plan with:

• Plan name and billing interval (monthly or annual)
• Status badge — Active, Trial, Canceling, or Past Due
• Renewal date — When your next billing cycle occurs
• Manage button — Opens the Stripe billing portal for payment method updates, invoice history, and receipts

Status-specific alerts appear automatically:

• Past Due — "Payment failed — please update your payment method to avoid service interruption"
• Canceling — Shows the exact date your plan will downgrade to Free, with option to resubscribe before then

Plans

Plans are displayed as a side-by-side comparison with a monthly/annual toggle at the top (annual plans typically offer savings). Each plan card shows:

• Plan name and description
• Price (monthly or annual per-month rate)
• Feature list with checkmarks and informational tooltips
• Action button: Upgrade, Downgrade, Current Plan, or Switch Billing

Upgrading: Click a higher plan's button to see a proration preview dialog showing:

• Credit for unused time on your current plan
• Charge for the new plan (prorated to your billing cycle)
• Net total charged today
• New recurring rate going forward

This ensures you never overpay — you always get credit for what you've already paid.

Downgrading: Same proration preview flow. Any unused credit from your current plan is applied to the lower plan's cost.

Switching billing interval: If you switch from monthly to annual (or vice versa) on the same plan tier, you'll see a proration breakdown showing the adjustment.

Canceling: Clicking "Downgrade" to the Free plan opens the Stripe billing portal where you can cancel. Cancellation takes effect at the end of your current billing period — you keep full access until then.

Credits

Below the plans section, a credit top-up card lets you purchase additional credits:

• Current credit balance displayed prominently
• Slider to select a credit package — drag to choose your amount
• Package labels showing available options with credit amounts and prices
• Purchase button — Opens Stripe Checkout for a one-time credit purchase

Credits are consumed by agent runs (AI model tokens, sandbox compute time, etc.). They supplement your plan's included allowance and never expire.

Billing Portal

For paid plans, the Manage Subscription button opens the Stripe billing portal where you can:

• Update your payment method (credit card, etc.)
• View and download invoices
• Review payment history and receipts
• Cancel your subscription

The portal is hosted by Stripe — fully secure and PCI-compliant. Your payment details are never stored on Communa's servers.