- Introducing Orpius
- Orpius Architectural Overview
- How Orpius Protects Your Data
- Default Hosting Location (managed service)
- Tenancy and Isolation
- Encryption at Rest
- Encryption in Transit
- Key Management
- Secrets and Sensitive Values
- Data Sent to Model Providers
- Access Control and Identity
- Auditing, Logging, and Monitoring
- Backups, DR, and Availability
- Secure Code Execution
- Data Retention and Deletion
- Compliance and Assurance (deployment-dependent)
- Security Quick Summary
- Getting Started with Orpius
- Installing the Orpius Console
- Setting up Orpius for the First Time
- For Developers: Integrating Orpius with Your Application
- Understanding the Orpius System Structure
- Understanding User Roles
- Navigating with the Orpius Console
- Understanding Agents
- Configuring a Custom Agent
- Empowering Agents with Tools
- Using Secrets to Store Sensitive Information
- Understanding How Work Starts in Orpius
- Using Operations to Connect Your Application to AI Agents
- Using Events to Trigger Activities
- Triggering Activities on a Schedule
- Understanding the Workflow and Activity Lifecycle
- Agent Activity Auditing and Verification
- Working with Isolated Storage
- Tracking and Restoring Changes with Git
- Creating and Hosting Websites or Lightweight Apps with Orpius
- Working with Orpius by Email
- Using Dialogs to Involve People
- Using Team Collaboration and Management
- Adding Users to a Space
- Next Steps and Further Resources
Orpius is a collaborative cloud workspace with built-in agent infrastructure, where people, teams, departments and external participants can work together with AI in a shared environment.
The idea is to move beyond AI as a one-to-one tool, where everyone works with their own isolated AI, and create a shared environment where people, systems and AI can all participate in the work.
You can use Orpius directly because it already comes with a lot of built-in tools and capabilities. Or you can connect your own applications and services and extend it further.
Orpius is designed for work that does not require someone to sit in front of the AI all the time. Most of the work can happen in the background, while people are brought in whenever they are needed.
Orpius has built-in ways for AI to ask questions, request information, seek confirmation or approval, and wait for a response before continuing with the work.
Security and privacy are built into Orpius as well. Data is protected at rest and in transit, access is controlled through permissions, and secrets are kept separate from AI conversations so credentials do not need to be exposed to the models.
Orpius provides a common environment where people and agents can work together.
You do not need to be a developer to use Orpius. Much of the platform can be used and configured simply by talking to an AI agent, either through the Orpius Console or by email.
Agents understand the Orpius environment they operate in and can use the platform itself on your behalf.
For example, you can say:
"Send Charlie an email with an interactive maths worksheet he can fill in and send back to you. Send it every second day, except weekends, so he can practise his times tables."
Orpius will create the schedule and instruct itself to make it happen:
Generate a worksheet containing 20 random multiplication questions for times tables from 1 to 10 (e.g., 1. 7 x 8 = ?, 2. 3 x 4 = ?).
Use the Dialog plugin to send this worksheet to @Charlie with the subject 'Times Table Practice Worksheet'.
Wait for the reply containing Charlie's answers.
Once the reply is received, grade the answers."
You can change the schedule at any time simply by telling Orpius what you want to change, or you can edit it manually from the Schedule tab.
For example, you can say:
"Please add to the instructions for the interactive times table practice schedule that if Charlie hasn't responded by 8pm that day, send him a reminder."
Orpius will update the instructions for that schedule accordingly.
In this example, Charlie is already a member of your Space, so Orpius knows who Charlie is and how to contact him.
Orpius also helps you discover what it can do simply by asking.
If you are not sure how something works, ask the agent. It can explain the feature and, where it makes sense, demonstrate it for you.
For example, you can ask how the Dialog works. The agent can explain it, then actually use it to send you an email asking for a response.
With Orpius, agents can:
- Work with you through natural conversation.
- Use tools and connected systems on your behalf.
- Create, manage and respond to schedules and events.
- Ask for information, confirmation or decisions when needed.
- Work with version-controlled files, including their history and previous states.
- Work alongside people and other agents in shared spaces.
- Explain and demonstrate the capabilities available to them.
Orpius provides a complete AI application platform without requiring you to build and maintain the underlying AI infrastructure yourself.
You can use Orpius as a:
-
Foundation for integrating AI into existing applications - Add agents, models, tools, automation, conversations, and intelligent processing to existing systems while Orpius manages the supporting infrastructure, security, routing, and communication.
-
Foundation for building new AI applications and services - Build AI-powered products on top of an existing platform for agents, tools, conversations, events, schedules, permissions, and integration.
-
Runtime for tools used by AI agents - Expose capabilities from your own applications and services so that authorised agents can use them as part of their work.
-
Platform for event-driven and automated AI workflows - Connect AI behaviour to events, schedules, applications, and external systems without having to construct the entire orchestration layer yourself.
Developers can concentrate on the capabilities that are specific to their application while Orpius provides the common foundation required to run them securely.
Orpius is designed so that you can start with the work you want done. If you can describe what you want, you can usually just ask Orpius to do it.
Of course, you can go much deeper if you want to. You can build sophisticated agentic environments, create Operations, connect internal and external systems, and control how everything works.
Orpius is built so AI can operate safely within a secure, auditable and reversible environment, where changes can be traced, and work can be reviewed or restored when needed. This makes it suitable for an individual, a team, a department or an entire organisation.
Here are some of the ways Orpius can create value.
You can use Orpius as a PA to arrange meetings for you, without revealing your email address or those of the other participants to the LLM.
Orpius handles the email addressing separately, so the agent can contact participants, receive their replies and continue arranging the meeting without their email addresses ever being sent to the LLM provider.
All you need to do is configure a meeting-scheduling Operation:
- Open the Operations tab in the Console and select the + button to add a new Operation.
- Give your Operation a name. Note that this name will also be used as the name in its email address. For example, you could call it My-AI-PA.
- Select the Agent you want to use. See Configuring a Custom Agent for how to create a custom Agent.
- Give the Agent its instructions. For example:
"You are my personal assistant.
Assist me with tasks as I direct you. You may be asked to create Google Calendar events and organise meetings for me with other Orpius users or people outside Orpius.
When arranging a meeting, check my availability, propose suitable times to the participants, deal with their replies, and create the calendar event once a suitable time has been agreed.
You can use the secrets:
GoogleCalendarClientId GoogleCalendarClientSecret GoogleCalendarRefreshToken "
- Select the Dialog tool
- Save the Operation
See Configuring a Secret for how to configure the required secrets.
At the bottom of the Operation page, copy its email address. You can now email your PA whenever you want it to arrange a meeting.
For example, you might say:
"Arrange a meeting next week with Sarah and James, and with Jim and Jo who I have CC'd on this email. Find a time that works for everyone and book it."
Because the Operation has access to your Google Calendar secrets, the agent can check your availability and create calendar events without knowing your calendar credentials. Secret values are handled by Orpius and are not included in the AI conversation or sent to the LLM provider.
The agent can find suitable times in your calendar, offer them to the other participants, deal with their replies and changing availability, and keep the conversation going until a suitable time is found. Once everyone has agreed, it can book the meeting in your calendar.
For people outside Orpius, simply CC the people you want the agent to contact when you send the request.
For members of your team, you can just refer to them by name. They are already known to Orpius, so the agent knows how to contact them.
In both cases, email addresses are handled by Orpius and are not revealed to the LLM. This includes your own email address as well as the addresses of the people you CC.
Orpius takes a different approach to working with email.
You do not need to give an AI access to your entire inbox. Instead, you send, forward or automatically forward the emails you want Orpius to process.
For example, you could automatically forward incoming invoices to an Operation that extracts the attachments, identifies the supplier, stores the files in the right place and records the relevant information.
Or you might simply forward a customer email and say:
"Please deal with this and send me the proposed response for approval."
Only the email you choose to send into Orpius becomes part of the work. The AI does not need permission to browse through the rest of your mailbox.
Email routing is also kept separate from the LLM. Your email address, and the addresses of people you copy or involve in the conversation, do not need to be revealed to the model.
Orpius can work alongside the applications and systems you already use.
For example, an existing application can raise an Event in Orpius when something happens, such as a customer submitting a form, a new record being created, or the status of something changing.
That Event can start an Activity, or a collection of Activities, which can then coordinate the work that needs to happen. Those Activities may in turn invoke Operations through Operation Relay, allowing more complex processes to be built from reusable pieces of work.
Applications can also invoke Operations directly, and Orpius can use tools and APIs to interact with your existing systems as part of the work.
This means you do not need to replace your existing applications to make use of AI. Orpius can sit alongside them and add AI-driven work where it is useful.
If you have an existing system or process you would like to connect to Orpius, contact us and tell us what you are trying to achieve. Our implementation team can help you work out the best way to structure the Events, Activities, Operations and integrations for your scenario.
The Orpius platform is deployed as a single-tenant cloud service. Support for on-premises deployments is planned.
The managed deployment is provisioned by default in Switzerland.
The following diagram illustrates the high-level architecture of an Orpius deployment. Each customer runs within a single-tenant environment, ensuring full isolation of compute, storage, and secrets. The Orpius Console (desktop application) connects securely to the Orpius Server, which manages authentication, scheduling, event handling, and access to encrypted storage. All sensitive operations such as code execution, tool calls, and secret retrieval, occur within this private environment. Where a model provider is used (for example, OpenAI, Google Gemini, Azure OpenAI, on-prem), Orpius connects through secure TLS channels while enforcing your chosen data-handling policies.
flowchart LR
subgraph Tenant["Orpius Deployment"]
Console["Orpius Console (Desktop)"]
Server["Orpius Server"]
subgraph Core["Core Services"]
Auth["Auth / Roles"]
Storage["Encrypted ZFS Datasets"]
Secrets["Secrets Vault / KMS"]
Events["Events Engine"]
Schedules["Scheduler"]
Tools["Tool Runner"]
Orchestrator["Workflow Orchestrator"]
CodeExec["Code Execution (wasm)"]
end
Providers["LLM Providers (OpenAI / Azure OpenAI / Gemini / On-prem)"]
end
Console <--> Server
Server <--> Core
Server --> Providers
Orpius groups everything you need; security, storage, tools, workflow, and optional LLM connectivity, inside a single-tenant boundary. The Console configures; the Server brokers; Core Services execute.
Note: A multitenant environment may be provided for evaluation and proof-of-concept testing.
Orpius is built with a defence-in-depth approach covering tenancy isolation, encryption, key management, access control, and operational safeguards. This section explains what happens to your data at rest, in transit, and while agents are running.
Unless otherwise agreed, each managed Orpius tenant is deployed in Switzerland. Tenant compute, encrypted storage (ZFS), snapshots and off-box backups are created and retained in our Swiss region by default.
-
Model providers You choose your model endpoints (e.g., Azure OpenAI, OpenAI, Gemini, on-prem).
-
Location Alternatives On-premises and other regional deployments are available on request.
- Single-tenant by design: Each customer gets a dedicated Orpius deployment. No compute, storage, secrets, or configuration are shared across tenants.
- Storage isolation: Each tenant is provisioned with its own encrypted ZFS datasets. Files, models, logs, and cached artefacts for one tenant are not visible to others.
- Process isolation: Code execution (for tools and sandboxes) is confined to WebAssembly (Wasm) sandboxes with no access to other tenants' processes or storage.
- ZFS native encryption: All tenant datasets are encrypted using AES-256 (ZFS native encryption). Keys are unique per dataset and never reused across tenants.
- Backups and snapshots: Snapshots and off-box backups are encrypted before leaving the tenant host. Restores can only be performed with the tenant's keys.
- Key rotation: Dataset Encryption Keys (DEKs) are wrapped by a Key-Encryption Key (KEK). KEKs can be rotated without re-encrypting stored data.
- TLS everywhere: All network traffic between Console, Server, and internal services is protected with TLS (TLS 1.2+; TLS 1.3 preferred).
- Strict ciphers and HSTS: Strong cipher suites are enforced and HTTP is redirected to HTTPS with HSTS.
- Mutual trust internally: Internal service-to-service calls use authenticated channels and scoped service identities.
- Per-tenant keys: Every tenant has distinct KEKs; DEKs are generated per dataset/resource. Keys are never shared between tenants.
- Hardware or cloud KMS: Keys are stored in a secure keystore.
- Rotation and revocation: KEKs can be rotated on a schedule or on demand. Access to retired keys is revoked immediately.
- Secret references, not values: When an agent speaks to a model, Orpius substitutes secret references (e.g.
<%=Key:WeatherKey%>) in prompts. The real values are only resolved at tool-execution time inside Orpius, never in the model prompt. - Scoped retrieval: Secrets are decrypted only when a permitted tool call requires them, and only for the duration of that call.
- Auditability: All secret access is logged with timestamp, requesting agent/tool, and outcome (without logging the secret value).
- Minimised prompt payloads: Orpius strips secret values and any fields explicitly marked sensitive before sending prompts to model providers.
- Provider controls: You choose the model provider (e.g. OpenAI, Azure OpenAI, on-prem).
- Role-based access: Space and Organisation roles constrain who can view, configure, or execute agents, tools, events, operations, files, and logs.
- Least privilege by default: All built-in tools are disabled for customer-facing Operations until explicitly enabled.
- Strong auth: Support for email-verified accounts.
- Tamper-evident logs: Security-relevant events (auth, key use, secret access, tool execution, data export) are recorded with integrity protection.
- Alerting: Abnormal access patterns and repeated failures raise alerts to system owners.
- Retention: Log retention is configurable per tenant ([default N days]).
- Encrypted backups: Backups inherit tenant encryption; keys never leave the keystore.
- Restore testing: Periodic test-restores validate that encrypted backups are recoverable.
- High availability: Core services run behind health-checked load balancers; background workers are horizontally scalable.
- Wasm sandbox: The CodeExecution tool runs user code inside a Wasm sandbox with constrained CPU, memory, filesystem, and network policies.
- No lateral movement: Sandboxes cannot access other tenants' storage, processes, or secrets unless a secret is explicitly granted to the tool call.
- Egress control: Outbound network access from sandboxes can be disabled or restricted to allow-lists.
- System-wide retention controls: System Settings include configurable data-retention periods that apply to spaces, files, logs, caches, and other artefacts.
- LLM interaction retention: Messages sent to and from model providers are retained for 30 days by default and only to let users resume conversations. They are not used for model training. You can shorten or extend this period (including retention-off) in System Settings.
- You control retention: Per-space policies can purge files, chat transcripts, tool outputs, and model caches after a defined period.
- Right to delete: When you delete a space or organisation, Orpius schedules a secure erase of the tenant datasets and removes all wrapped keys after the retention window closes.
- Search indices and caches: Derived artefacts (indexes, embeddings, caches) follow the same retention and deletion policies as the source data.
- GDPR support: Configurable retention, export on request, and secure deletion workflows support GDPR principles (purpose limitation, storage limitation, data minimisation) and user rights (access/erasure) for deployments that require them.
flowchart LR
subgraph Settings["System Settings: Retention"]
Files["Files / Storage"]
Logs["Logs"]
LLM["LLM Interactions (30 days default)"]
Caches["Caches / Indexes"]
end
Files --> Policy["Retention Policies"]
Logs --> Policy
LLM --> Policy
Caches --> Policy
Policy --> Purge["Auto Purge / Secure Erase"]
Purge --> Deletion["Key Removal & Dataset Erase"]
- Change management: Infrastructure and application changes are reviewed and tracked.
- Vulnerability management: Regular dependency scanning, OS patching, and penetration testing.
- Compliance mappings: Controls map to common frameworks (e.g. ISO 27001, SOC 2); attestations available on request for managed deployments.
- Separate, encrypted storage per tenant (AES-256 on ZFS).
- Distinct keys per tenant; secrets never sent to models.
- TLS in transit; Wasm sandbox for code.
- Least-privilege defaults; full audit trail.
- LLM interactions kept 30 days by default for conversation continuity only. (deployment-dependent)
- Encrypted backups; tested restores; configurable retention; supports GDPR compliance.
Before you can start working with Orpius, you will need:
- Orpius Console: A lightweight desktop client for configuring everything from models to agents and tools. You can download a trial version of the Orpius Platform, see Trial Version section. If you would like a production instance, please Contact Us.
- Access to your own LLM provider Orpius connects to the AI models you choose, whether hosted on-premises or in the cloud. It currently supports Google Gemini, OpenAI, Azure OpenAI, with more providers to follow. Many third-party providers also use the OpenAI Chat Completions format, making them compatible with Orpius.
- Access to an Email Server (System Owners only)
Because Orpius runs in your own private cloud, email handling is not provided as a shared service. An email server is required during initial setup so new users can verify their email addresses (a sending-only server is sufficient). It will also be used to send notifications or messages to team members.
If you want to test drive Orpius, we provide a free trial version for evaluation. See the Trial Version section for details.
The Orpius Console is a lightweight desktop application that connects directly to the Orpius infrastructure.
To get started, you will receive a message from us containing:
- A link to download the Orpius Console, resembling:
https://<YourAppName>.app.orpius.com/console/ - The Orpius Server URL.
- Your Access Key (system owners only).
Follow these steps:
- Open the download link and click Download Orpius Console.
- Run the installer after the file finishes downloading.
- Once installation is complete, launch the Orpius Console.
- Enter the Server URL into the field provided.
- Enter the Access Key (system owners only).
If you would like to evaluate Orpius before requesting a dedicated single-tenant production instance, you can download the trial version from our website: Download the Orpius Console (Trial)
The trial environment runs on a shared, capacity-limited multi-tenant instance. The trial stack may be reset or removed without notice.
If you are the system owner of an Orpius installation, you will be prompted to set up the system the first time you launch the Orpius Console.
During the first-time setup of the Orpius server, you will be prompted to enter your email server details. The email server is used by Orpius to handle email requests such as sending messages to team members. Setting up the email server is required because it allows new users to verify an email address.
Enter your email server details. You can update this information later in System Settings within the application.
Every Orpius user creates and signs into a user account.
During the first time setup, you will be prompted to create your account.
- Enter your account Username, Email, Given Name, Surname and Password into the fields provided.
Note: At present, account information can't be changed after your account is created. Options to update these details will be available in an upcoming version.
You will receive a confirmation email from the system address you configured during email server setup (e.g. noreply@yourdomain.com) containing a code.
If you see an error message, click Previous and check that your email address and email server information are correct.
Orpius can be integrated into existing applications or used as the foundation for new AI-powered systems. A typical integration involves three steps:
- Configure Orpius - Define the agents, models, tools, events, and operations your application will use. Much of this can be configured through the Orpius Console.
- Connect your application - Use Orpius operations, events, tools, APIs, and SDK libraries to connect your application to Orpius. Operations provide a primary way for your application to invoke AI capabilities, while tools allow agents to call functionality exposed by your application.
- Run and orchestrate - Once connected, agents can use your application's tools and respond to operations and events. Orpius manages the supporting orchestration, state, storage, communication, and security.
sequenceDiagram
participant U as You (User)
participant C as Orpius Console
participant S as Orpius Server
participant A as Agent
participant T as Tool(s)
participant P as External System/API
U->>C: Configure Models, Agents, Tools, Events, Operations
C->>S: Save configuration
U->>P: Call Operation from your app
P->>S: Invoke Operation (External ID + Access Key)
S->>A: Dispatch request (with allowed tools)
A->>T: Call tool(s) as needed
T->>P: (Optional) Call external API
T-->>A: Return results
A-->>S: Compose response
S-->>P: Return operation response
Configuration to Execution (end-to-end flow)
Orpius is organized around organizations and spaces. At the top level is the System, which represents the Orpius installation itself. Within the system, there are multiple organizations.
The Organization represents your company or organization. Each organization has its own storage allocation, and set of members.
Each Organization contains one or more Spaces. A Space is a dedicated workspace for a specific project or team. Each Space contains all the resources for that project, such as agents, tools, models, operations, and events, and has its own isolated storage area.
mindmap
root((Orpius System))
Organization A
Space A1
Space A2
Organization B
Space B1
Space B2
Organization C
Space C1
Space C2
The Orpius system contains organizations, which contain spaces
For guidance on working within a Space in the Console, see Understanding Spaces
Note: When a user registers with Orpius, a default organization and space are created automatically for that user. You may invite other users to join your organization and collaborate in the same space.
A user may have different roles across different organizations and spaces.
- Participant: Can receive notifications and perform tasks.
- Editor: Able to create and modify content and manage schedules and events in the space.
- Administrator: Able to add new members and manage space settings.
- Owner: Able to delete the space or assign administrator privileges.
- Participant: A member of a space within the organization.
- Administrator: Able to add or remove members and manage organization settings.
- Owner: Able to delete the organization or assign administrator privileges. Able to manage language models.
After completing the initial setup, Orpius opens in the Space Selector view, where you can see a list of the Spaces you belong to. Each user begins with a default Space that is created automatically.
A space is your working area inside the Orpius Console. Each space keeps everything related to a project or team in one place. You can also invite members (inside or outside your organization) to collaborate in a space. Members can be invited into a space and granted access through roles.
Your Spaces are listed on the Space Selector view, where you can:
- Open an existing space
- Create a new space
- Delete a space
Within a Space, you can:
- View notifications
- View and manage scheduled tasks
- Upload and download files to and from your isolated storage
- Invite and manage members for collaboration
- Configure your models, agents, tools, operations, secrets, and events
- Interact with AI agents via chat
To create a new Space:
- From the Organization View page, select Create a Space.
- Enter a name for the Space.
- Confirm to create.
To switch to another Space, sign out of your current session. When you sign back in, the Organisation View opens and lets you choose a different Space.
The system is designed to work with any LLM, whether hosted on-premises or in the cloud. Currently, OpenAI, Azure OpenAI, Google Gemini, DeepSeek, and Mistral are supported today, with more to follow. Any provider that implements the OpenAI Chat Completions format can be used with Orpius.
You can configure as many models as you need, from different providers. For example, some agents might use GPT-4o for complex tasks, while others can run on a lower-cost model such as OpenAI gpt-4o-mini.
Caution: When your system is configured for unattended execution, such as for scheduled tasks, events or operations, it may continue to consume resources and incur costs even when no users are actively connected.
Tip: Google provides free API access to its Gemini model API, which is useful for getting started with Orpius.
flowchart LR
subgraph Orpius
Models["Configured Models (multiple)"]
Policy["Provider Policies (no training, region pin)"]
end
User --> Models
Models -->|Request| Provider1["Azure OpenAI"]
Models -->|Request| Provider2["OpenAI"]
Models -->|Request| Provider3["Gemini"]
Models -->|Request| Provider4["On-prem LLM"]
Policy -.applied to.-> Models
When Orpius talks to a model, it follows a structured loop that lets the model both reply and call tools:
- A Prompt Originator (for example, a user chat, an agent running a task, an event, a schedule, or an Operation) sends a text prompt to Orpius.
- Orpius calls the configured LLM, supplying the prompt, conversation context, and the set of tools the model is allowed to use.
- The LLM returns a JSON response that can contain:
- 0 or 1 messages for the Prompt Originator, and
- 0 or more tool call requests (API/tool invocations).
- If there is a message, Orpius delivers it back to the Prompt Originator. In parallel, Orpius executes any requested tool calls. Each tool call either returns a normal result payload or an error payload.
- As tool results become available, Orpius sends them back to the LLM. The model can then:
- send an updated message to the Prompt Originator, and/or
- request further tool calls.
- This cycle repeats until the LLM stops requesting tools. At that point, Orpius delivers the final message to the Prompt Originator and the interaction completes.
sequenceDiagram
participant PO as Prompt Originator<br/>(chat/agent/event/schedule/operation)
participant OS as Orpius Server
participant LLM as LLM Provider
participant TL as Tools / APIs
PO->>OS: Send prompt and context
OS->>LLM: Call model<br/>with tools + history
loop Tool-calling loop
LLM-->>OS: JSON: message (0..1)<br/>+ 0..n tool calls
opt Deliver message
OS-->>PO: Assistant message (if present)
end
alt One or more tool calls
par Execute each tool
OS->>TL: Execute tool/API
TL-->>OS: Tool result or error
end
OS->>LLM: Send tool results<br/>as follow-up
else No tool calls
OS-->>PO: Final message (if any)
end
end
- Open the Models view from the sidebar
- Select the Add (+) button in the toolbar of the Models view
- Enter the required information
- Save
In Orpius, agents are considered users, just like humans. Orpius includes two built-in agents: Orpius and Phaedra.
- Orpius is the agent you interact with directly through chat, and who orchestrates non-interactive activities.
- Phaedra carries out non-interactive activities, such as scheduled tasks and event execution.
Both Orpius and Phaedra are organization-wide agents available in every space. In addition, you can create custom agents dedicated to specific operations within a space, allowing you to provide a custom persona and instructions to your agent.
By default, Orpius and Phaedra use the first LLM you define, but you can assign them to any of your available LLMs.
Agents in Orpius do not have fixed tools or workflows of their own. Instead, they draw from a shared pool of tools.
When integrating your application with Orpius, you configure a Custom Agent. This agent will handle all incoming requests from your application.
To create a custom agent, perform the following steps:
- Open the Agents view from the sidebar
- Select '+' button in the toolbar of the Agents view
- Give the Agent a Name
- Select a suitable Model for your Agent
- Define the Agent's Persona
- Set the Agent's Temperature
- Provide further Instructions that will assist the agent in carrying out its duties.
- Save.
Configuring a custom agent
Tools are functions that your agent can call to perform specific tasks. Tools in Orpius are not tied to a single agent. They live in a shared pool that any agent can access if it has permission. Tools can be combined, triggered by events, and reused across different agents. Agents can autonomously select and combine the tools they need to complete a task.
Tools can be either built-in or custom.
The diagram below illustrates how Agent Tools operate within Orpius. All built-in tools such as the Scheduler, Notifier, WebPageRetriever, and CodeExecution, are system-wide features that are configured at the organisation level. Organization Administrators can enable or disable specific built-in tools.
When you create a Operation, you can selectively grant access to any of these built-in tools for that Operation. Your custom agent will then be given access to the built-in tool during the Operation. This structure ensures consistent capability management across the organisation while maintaining fine-grained control over what each agent can perform.
flowchart TB
subgraph Org["Organisation Configuration"]
SharedTools["Built-in Tool Pool"]
CodeExec["CodeExecution (Wasm)"]
Notifier["Notifier"]
WebGet["WebPageRetriever"]
Etc["… (other built-in tools)"]
end
subgraph Agents
Orpius["Orpius (Built-in Agent)"]
Phaedra["Phaedra (Built-in Agent)"]
CustomA["Custom Agent"]
end
Org -->|Enable / Disable Tools| SharedTools
SharedTools --> Orpius
SharedTools --> Phaedra
SharedTools -->|Selected subset| CustomA
Built-in Tool Use
Custom tools are provided by customer-hosted or third-party servers that register with Orpius as tool providers. These tools are ephemeral; they are not stored or managed within a space, but can be made available to built-in or custom agents when they are online and registered. When your application calls an Operation endpoint in Orpius, it must explicitly specify which custom tools are permitted for that call. This ensures that only the declared tools can be invoked during the request, providing fine-grained control, isolation, and clear auditability for every interaction. For more information on registering tool providers and specifying tools in operation calls, see the Orpius SDK Developer Guide.
flowchart LR
App["Your Application"]
OpCall["Operation Call (specifies allowed custom tools)"]
Orp["Orpius Server"]
CTProvider["Custom Tool Provider (customer or third-party server)"]
SDK["Orpius SDK"]
App --> OpCall --> Orp
CTProvider -->|Registers with External ID + Access Key| Orp
Orp -->|Invokes permitted tools| CTProvider
CTProvider -->|Returns results| Orp
Orp -->|Sends response| App
Custom tools are provided by customer-hosted or third-party servers
Orpius includes the following set of built-in tools:
- Scheduler – Allows an AI agent to add work items to be done at a future time.
Schedules can be of the type:
- Daily - to run at a specified time
- Weekly - to run on a specified day of the week and specified time
- Monthly – to run on a specified day of the month and time
- Yearly - to run on a specified day of the month and time
- Interval - to run after a specified period and may be set to repeat forever or loop for a specified number of times.
- WebPageRetriever – Retrieve the HTTP response for a specified URL. Allows for the use of web APIs.
- WebSearch – Allows an AI agent to search the internet. A search provider API key is required.
- Notifier – Send notifications to a user. A notification may also be sent by email to the user. The user's email is never provided to an agent.
- CodeExecution – Compiles and runs managed code and passes the results back to the agent. This allows the assistant to complete tasks that require calculations, storing and retrieving data from files, or calling third-party APIs. The execution environment is sandboxed and hosted within WebAssembly (Wasm), isolating it from other processes or code execution.
- ImageAnalysis – Allows an agent to analyze an image, either from a specified image URL or by snapping a frame from a real-time video stream.
- VideoFeedMonitor – Connects to a real-time streaming protocol (RTSP) feed and captures a still image for analysis.
- EventRegistry – Registers an event name that can be used by a remote API to trigger a task. The identifier can then be used with a web hook in the system.
- Memory – Allows an agent to add a record of an event or experience to the agents memory store, enabling it to track changes across multiple tasks.
- EventTrigger - Triggers an event that was previously registered.
- OperationRelay - Allows an agent to call an Operation directly; enabling agent-to-agent communication, and facilitates the testing of Operations via the Orpius Console.
- Git - Every Orpius workspace is backed by a Git repository, with file changes committed automatically. Agents can inspect history, compare versions, identify changes, and restore earlier states, providing built-in traceability and version control without requiring users to manage Git themselves.
- Dialog - Let agents start conversations with you or other team members when they need input, information, confirmation, or a decision. Dialogs can support anything from a simple question to an ongoing conversation while work continues around it.
- Email – You can think of Email as another interface into Orpius. You can send the agent a question, send it work, send it files, or address an operation designed for a particular purpose. And because the operation already has its tools, instructions and context, you do not have to explain the mechanics of what should happen with every email. For example, you might email a Webmaster operation with changes you want made to your website and let Orpius handle the work.
The following example shows how a simple instruction can lead the agent to autonomously combine multiple tools to complete the task.
Prompt:
Add a scheduled item for every 5 minutes to analyze rtsp://orpius:<%=Key:WebCam%>@CAMERA_IP:554/cam/realmonitor?channel=1&subtype=0. Please record the car colors and their position in the bays to a csv file named 'parking.csv' by appending to the file. If it doesn't exist, create it with the column headers. If it already exists then append the data to the file without the headers. Include a row for each car you see. Notify John if cars are parked in the restricted space.
What the agent does:
- Attends to the task every five minutes (Scheduler)
- Retrieves the video stream URL (Secrets)
- Connects to the video stream (VideoFeedMonitor)
- Analyzes the image to detect parked cars (ImageAnalysis)
- Writes the findings to a file (CodeExecution)
- Notifies the user if an issue is detected (Notifier)
Tip: When scheduling an activity, be specific about the number of times you want the activity to run, or whether it should repeat indefinitely. The repetition count and the maximum number of repetitions is shown in the Schedule view. If not present, it indicates that the activity will run indefinitely.
Schedule Repetitions
In addition to the built-in tools, you can register your own custom tools located within your organization's network or on another external system. Custom tools extend Orpius with domain-specific capabilities that your agents can use during inferencing.
Custom tools can expose almost any functionality available within your environment.
For example, you can create tools that:
-
Connect to your organization's database
-
Access internal APIs
-
Perform domain-specific calculations or lookups, such as pricing estimates, scheduling logic, or engineering models.
-
Interface with third-party systems (e.g., ERP, CRM, or ticketing platforms) through secure API calls.
-
Trigger automation tasks such as sending notifications, generating reports, or updating shared files.
Each custom tool is registered in the system with a unique name and made available to AI Agents under your control. This allows agents to call your organization's existing code, libraries, or services securely, without exposing them externally.
- Register a custom tool: Open the Agent Tools view from the sidebar and select Custom Tools.
- Integrate with your application: Copy the External ID and Access Key, then paste them into your application.
- Expose functionality to Orpius:
Decorate your code with the
[Tool]and[ToolMethod]attributes. - Execute: The Orpius SDK automatically receives and dispatches tool requests at runtime.
For a deep dive into custom tools, see the SDK documentation for more details on custom tools. Example implementations are included in the downloadable SDK.
Secrets are used to securely store sensitive information such as API keys, tokens, or passwords. These secrets can then be referenced in chat, code, or tool calls without exposing their actual values to language model providers.
Agents are not automatically told which secrets are available. If you want an agent to use a secret, mention it in your prompt or instructions by name. For example:
You can use the following secrets:
- GoogleCalendarClientId
- WeatherAPI
The agent can then reference those secrets when carrying out the work, without needing to know their actual values.
When interacting with an LLM provider, the system sends the secret reference (e.g., <%=Key:SecretName%>) rather than the actual value. The value itself is only resolved at runtime by the system when needed for a tool call.
Note: If a secret value is returned from an API or other external service as part of the agent's output, it may become visible to the LLM provider. Avoid exposing secret values in responses or messages wherever possible.
This mechanism helps ensure that sensitive data is not hardcoded and remains protected throughout normal operation.
sequenceDiagram
participant Agent as Agent
participant Orp as Orpius Server
participant Vault as Secrets Vault/KMS
participant Tool as Tool Runner
participant LLM as Model Provider
Agent->>Orp: Prompt with <%=Key:WeatherKey%>
Orp-->>LLM: Prompt (secret reference only)
Agent->>Tool: Execute (needs API key)
Orp->>Vault: Decrypt WeatherKey
Vault-->>Orp: Key (in memory)
Orp->>Tool: Inject key at runtime
Tool-->>Orp: Result
Orp-->>Agent: Result
To create a new Secret:
- Open the Secrets view from the sidebar
- Select the Add (+) button in the toolbar of the Secrets view
- Enter the Token, the Secret Value and a Description
- Save your changes
Suppose you have an API key stored as a Secret named WeatherKey. In your instructions to an agent, you would reference it like this: <%=Key:WeatherKey%>.
For example, you might instruct the agent to:
Fetch the current weather
from https://www.weatherserviceexample.com?apikey=<%=Key:WeatherKey%>
When the agent executes this instruction by calling a tool, the Orpius system replaces the secret reference with the actual API key value. This allows the API key to be securely injected at runtime without being exposed to the LLM provider.
There are several ways to start work in Orpius. The appropriate one depends mainly on what should cause the work to begin.
- Chat - Use Chat when you want to work with Orpius interactively.
- Operation - Use an Operation to define a reusable kind of work that can be called when needed by a person, application, email or another part of Orpius.
- Event - Use an Event when work should begin because something has happened.
- Schedule - Use a Schedule when work should begin at a particular time or repeat at defined intervals.
- Email - Use Email when it is a convenient way for a person or system to send work, information or files to Orpius. Email can also be routed directly to an Operation.
These mechanisms define or initiate the work. They do not require you to create a separate AI agent for every individual task.
For example, you do not need to create a separate AI agent just to handle customer complaints. Instead, you can create a Customer Complaint Operation that describes how that work should be done.
A complaint might arrive when a customer submits a form, triggering an event, or when someone forwards a complaint by email. In either case, Orpius can invoke the same Operation and carry out the work using the agents, tools, instructions and context already available in the environment.
Operations allow your own application to communicate directly with agents defined in Orpius.
To create a new Operation:
- Open the Operations view from the sidebar.
- Select the '+' button in the toolbar of the Operations view.
- Choose the Agent that will receive and process incoming requests.
- Configure any Agent Tools that the Operation may use.
- Save.
Define an Operation
The Agent Tools section lists the built-in tools available to the selected Agent. You can enable or disable individual tools depending on the purpose of the Operation.
Some built-in tools, such as Code Execution or Notifier, may expose capabilities that are not suitable for customer-facing Operations. For example, the Code Execution tool can write to isolated storage, and the Notifier tool provides awareness of team members. For security reasons, all tools are disabled by default.
Note: If you plan to allow your agent to trigger events, enable the EventTrigger tool.
If the Operation is not externally facing, you may enable additional tools as required. Alternatively, you can instruct an agent to raise an Event that is handled by a full-trust agent such as Phaedra. This approach separates potentially sensitive activities from untrusted entities. This is discussed in more detail in the Events section.
After saving the Operation, the External ID and Access Key properties become available.
These values are used when connecting from your own application:
- The External ID identifies the Operation within Orpius.
- The Access Keys allow authenticated access. Two keys are provided so that one can be rotated without downtime.
Connecting to an Orpius Operation is covered in detail in the Development Guides.
Fields become available once the operation is saved
With an Operation in place, your application can communicate directly with an AI Agent through the Orpius platform.
Sample application communicating with an Orpius Operation
In addition to the built-in tools provided by Orpius, you can register your own custom tools hosted within your organisation's network.
To allow Orpius to call your tools, the system must know the publicly reachable URL of your server. Because development environments often run on localhost, we recommend creating a secure tunnel.
Learn how to create a secure channel
For language-specific setup and APIs, visit the Development Guides.
The OperationRelay is a built-in tool that allows an Agent to call an Operation.
It can be used when an Agent is invoked as part of:
- a scheduled item
- an event activity
- another operation
- an interactive chat
Each of these is considered an origin. The OperationRelay decides what information is required based on the relationship between the origin and the target Operation.
When calling an Operation, OperationRelay behaves as follows:
-
If the Operation being called is located in the same Space as the origin (for example, a schedule, event, operation, or chat in that Space), then only the Operation's External ID is required.
-
If the Operation being called is located outside the Space of the origin (for example, the origin is in one Space and the Operation lives in another Space or on a different Orpius server), then the following must be provided:
- the URL or server on which the Operation resides, and
- the AccessKey of the Operation.
Tip: It is best practice to provide the AccessKey to the agent as a Secret.
This allows you to control exactly which Operations can be called from which contexts, and under which credentials.
The ability to call an Operation directly from within Orpius opens up several important capabilities:
-
Agents can call other Agents An agent associated with one Operation, Event, or Scheduled Item; can trigger another Operation that is handled by a different agent.
-
Agents can communicate across servers and organisations Agents can communicate with other agents on a different Orpius server, potentially across company or organisational boundaries, enabling federated reasoning while each side keeps its own data local and private.
-
Easier testing of Operations Because Operations can be called directly via OperationRelay, you can use the Orpius Console to trigger and inspect your Operations more easily and confirm that they behave correctly.
-
Stronger least-privilege access You decide which target Operations may be called and which credentials are used. OperationRelay does not grant any implicit access; cross-space or cross-system calls always require explicit URLs and AccessKeys.
Just like when chatting with Orpius, or communicating with an AI user via an Operation, calls made through OperationRelay participate in the same conversation model.
This means:
- an origin (such as a chat, event, schedule, or operation) can call another Operation via OperationRelay
- the resulting interaction can resume and continue a conversation using the ConversationId
- context can be maintained over multiple interactions, even when work is delegated across Spaces or servers
OperationRelay allows an Operation on one node to invoke an Operation on another node, which itself runs the same model–tool loop. In principle, Operations can trigger further Operations across nodes, subject to configured limits.
sequenceDiagram
participant Origin as Origin<br/>(Chat/Event/Schedule/Operation)
participant OSrc as Orpius Server (Origin Space)
participant OR as OperationRelay
participant ODest as Orpius Server (Target Space/System)
participant Op as Target Operation
Origin->>OSrc: Request to call Operation (via OperationRelay)
OSrc->>OR: Invoke OperationRelay with<br/>ExternalId [+ URL + AccessKey if remote]
OR->>ODest: Call target Operation<br/>(URL, ExternalId, AccessKey, context)
ODest->>Op: Execute Operation
Op-->>ODest: Result
ODest-->>OR: Normalised response
OR-->>OSrc: Return tool result
OSrc-->>Origin: Continue conversation with updated context
Orpius tool-calling loop with OperationRelay.
From the user's perspective, this feels like a single, seamless operation; behind the scenes, OperationRelay is handling routing, credentials, and context for you.
Events provide a secure and flexible way to connect your systems with Orpius. An Event represents something that has occurred, either externally (for example, from your application or a monitoring system) or internally (from an agent or activity inside Orpius). When triggered, an event causes one or more activities to run automatically within its space.
Events can therefore be used to:
- React to real-world or system events (for example, an incoming webhook or sensor signal)
- Allow agents to chain actions together (for example, "if this happens, trigger that event")
- Safely delegate actions to another agent or system with different permissions
There are two ways to define an event in Orpius: manually or through chat.
Orpius understands what events are, and can be instructed through chat to create new events with specific actions.
- Start a new Chat
- For example, you could say: "Create an event named 'FactoryUnitArrived' that notifies the user robertB with the order details."
- Orpius will then register the event and set up the event activity instructions accordingly, including your username for proper execution.
- Open the Events view to review or modify the newly created event.
Figure X: Creating an event
Caution: When defining activities triggered by an event, avoid wording that suggests creating or scheduling an event in the task instruction. The agent may interpret this as a command to create a new event each time it runs. Instead, phrase the instruction as an immediate action, and review the event activity after creation to ensure it aligns with your intent.
To create an event manually, follow these steps:
- Register the Event
- Open the Events view from the sidebar.
- Select the '+' button in the toolbar of the Events view
- In the Event Configuration view, enter the event name (for example, FactoryUnitArrived).
- Define the Triggered Work (Activity)
- In the Event Triggered Work view, select the '+' button in the toolbar of the Event Triggered Work view.
- Provide a Title and clear Instructions for the agent (for example, "send a notification to the user with username robertB").
- You can define multiple activities for the same event.
- Allow the use of custom tools that the agent can use when executing the task.
- Trigger and Execute
- When an external system fires the FactoryUnitArrived event, an agent automatically executes the defined activity.
An event in Orpius can be triggered in two distinct ways:
- Externally: by calling its unique HTTP endpoint from another system or application.
- Internally: by name, using the EventTrigger tool from within any activity, schedule, or operation in the same space.
flowchart TB
subgraph External["External System"]
ext["App / Sensor / API"]
end
subgraph Space["Orpius Space"]
agentNode["Agent (uses EventTrigger tool)"]
eventNode["Event (registered)"]
activityNode["Triggered Activity"]
end
ext -->|HTTP GET or POST| eventNode
agentNode -->|Trigger by name| eventNode
eventNode -->|Runs defined actions| activityNode
Trigger an Event by External URL or Internal Name
This dual triggering mechanism allows powerful, composable workflows. For example, an agent performing an analysis task might detect an anomaly and then use the EventTrigger tool to raise an internal event, causing another agent to send alerts or collect data.
You can also instruct an agent to trigger external events by using the full HTTP endpoint, allowing cross-space, cross-organisation, or even cross-Orpius-system communication.
Built-in agents as well as your custom agents can trigger events. You can instruct Orpius, in a chat, to trigger an event by name. You can instruct your custom agent to trigger an event as part of an operation. Events can be triggered in scheduled tasks, operations, directly via a chat, or even conditionally during another event activity.
Upon registering an event, you add the activities or follow-up events that should run when the event is triggered. When the event is triggered, an agent performs the associated activities.
Editing an event activity
By clicking and expanding the URL for Access Key 1 or URL for Access Key 2, you can see the full URL to call the event. The purpose of having two access keys is to allow you to rotate one key without having downtime.
For example, given a different base URL for an Orpius application you will see something like:
https://nyfqg7nhtfak2vj6kjslml4lrk.app.orpius.com/api/v1/event/raise?event-id=a1267fa8ce2a20734536920ebdffa262
When called with a HTTP GET or POST request, this will trigger the event whose ID is a1267fa8ce2a20734536920ebdffa262.
The query string, which includes the 'event-id' parameter, also allows you to pass additional parameters to the agent and to your tools.
- A camera sends a motion detected event.
- You configure this event to trigger an activity with instructions that are given to an agent.
- Upon the event, the agent orchestrates the response: it launches the analysis, notifies the right user, and, depending on the outcome, can automatically trigger follow-up actions such as raising an alert, starting a recording, or handing off to another tool.
Note: Currently, events are handled by the built-in Orpius agents only. We plan to extend this functionality to custom agents in a future release.
Orpius is designed to be adaptive rather than follow rigid workflows. To keep this behaviour reliable, you can set guardrails by defining which tools and constraints an agent is allowed to use.
The event system can also provide a built-in security layer based on the principle of Segregation of Duties (SoD). Customer-facing agents can trigger events to request actions from more privileged agents, without having direct access to sensitive capabilities such as scheduling, storage, or team information.
When an event is triggered, you can pass additional parameters that are provided either to your tools only, or to your tools and your agent.
Key value pairs are passed in the query string for both GET and POST requests. In addition, for POST requests, raw JSON can also be passed directly to the agent in the body of the request.
- Query string keys that are prefixed with an underscore ( _ ) are passed to your tools only.
- Query string keys that are not prefixed with an underscore are passed to both your tools and the agent.
When using POST all key/value pairs (apart from the event-id) are supplied in the context object of your tools.
To see more information on the context property see Including Call Specific Information in a Chat in the Developer Guide.
Schedules allow you to define when an activity should occur. Once created, Orpius automatically manages the execution lifecycle: the Scheduler queues the task, and when the scheduled time arrives, Orpius selects the most suitable agent, based on its profile, availability, and assigned permissions, to carry out the work. After execution, an internal audit agent independently verifies that the task met its intended objective.
This automated orchestration ensures that work runs reliably, securely, and under the correct operational context, without requiring manual intervention.
flowchart TB
Define["Define Schedule (chat/UI)"]
Queue["Scheduler Queues Job"]
Select["Orpius Selects Suitable Agent"]
Run["Agent Executes Activity"]
Audit["Audit Agent Verifies Outcome"]
Repeat{"Repeat until count or end criteria met"}
Done["Complete"]
Define --> Queue --> Select --> Run --> Audit --> Repeat
Repeat -- Yes --> Queue
Repeat -- No --> Done
Scheduled activity lifecycle: Orpius queues, assigns, executes, and audits tasks automatically.
Note: Activities are also triggered by Events, which are covered in the previous section.
You can create a schedule directly in chat.
- Start a new Chat
- For example, you could say: "Please schedule an item to send me a joke every 2 minutes."
- Orpius will create a scheduled task, which you can then review, edit, or delete in the Schedule view.
- Open the Schedule view to review or modify the newly created schedule.
Tip: Be wary that running a task at very short intervals (such as every 2 minutes) can increase resource usage and cost. You should specify how many times the activity should repeat; otherwise, it will run indefinitely.
Every activity in Orpius, whether triggered by an event or a schedule, is managed by a dynamic workflow orchestration system. This system determines what work must be done, who should do it, and how the result is verified.
When a new task arrives, Orpius places it into an internal activity queue. From there, the Workflow Orchestrator analyses the task requirements, evaluates which agents have the necessary tools and permissions, and selects the most suitable agent to perform it. Once selected, that agent executes the activity under supervision, and the outcome is recorded for audit and review.
flowchart TB
Events["Events"] --> Q["Activity Queue"]
Schedules["Schedules"] --> Q
Q --> Selector["Agent Selector"]
Selector --> Exec["Assigned Agent"]
Exec --> Super["Supervisor"]
Super --> Audit["Audit / Verdict"]
Workflow orchestration and activity lifecycle.
- Event-triggered activities are generated by named events within a space.
- Scheduled activities are queued by the Scheduler to run at defined times or intervals.
The Agent Selection process determines which agent is most appropriate to handle each activity. Selection is based on:
- The agent's assigned permissions and accessible tools.
- The agent's profile description.
Once selected, the activity is handed to the agent for execution.
During execution, a Supervisor process tracks progress, timeouts, and runtime limits. If an agent encounters an error, exceeds policy limits, or becomes unresponsive, the Supervisor terminates the task and records the state for later analysis. All results, successful or not, are logged with the initiating context, timestamps, and any generated artefacts.
After completion, the activity and its output are passed to the internal Audit Agent, which reviews whether the outcome appears to satisfy the stated objective. The audit verdict ("Yes" or "No") and all related artefacts are stored in the system's immutable audit log.
To ensure that every automated activity in Orpius performs as intended, the platform includes an internal audit mechanism. After an agent completes a task, whether scheduled, triggered by an event, or invoked through an operation, an internal audit step runs automatically to verify the outcome.
sequenceDiagram
participant Exec as Performing Agent
participant Log as Activity Log
participant Aud as Audit Agent
participant Admin as Admin/Viewer
Exec->>Log: Record objective + outcome
Log-->>Aud: Provide artefacts
Aud->>Aud: Compare outcome vs objective
Aud-->>Log: Verdict: "Yes" or "No"
Admin-->>Log: Review audit trail & verdict
- When an agent finishes an activity, Orpius records the original instructions (objective) and the observed outcome.
- A separate internal Audit Agent then examines these artefacts.
- The audit agent independently evaluates whether the outcome appears to meet the stated objective and records a simple verdict of "Yes" or "No."
- Integrity and reliability: Confirms that AI-driven activities complete as requested.
- Automated oversight: Provides continuous self-assessment without human review.
- Error detection: Highlights potential failures or incomplete results.
- Traceability: The audit record, verdict, and related context are logged for review in the system's audit trail.
- The audit agent operates entirely within your Orpius deployment and uses the same encryption and isolation protections as other components.
- No data from this process is shared externally or sent to language-model providers.
- Audit results are immutable and form part of the tamper-evident log history used for compliance and diagnostics.
This built-in verification mechanism ensures that AI agents in Orpius remain accountable, observable, and auditable. It strengthens confidence in autonomous operations, supports internal governance processes, and contributes to compliance assurance frameworks such as GDPR, ISO 27001, and SOC 2.
Each space has its own isolated storage area.
Files uploaded to isolated storage are available exclusively to users and agents operating within the same space. This provides a secure way to share data, documents, and other resources with agents and users on your team.
Agents can read, write, and modify files within this storage.
For example, you could upload a sales report and ask Orpius:
"Summarise the key trends from last quarter's sales and write the summary to a file called SalesSummary.txt. If the file already exists, append to it."
Access to files within a space is controlled by permission levels. Users with a space role above Editor have access to files in that space.
- Open the Files view from the sidebar
- Click the Upload button in the toolbar of the Files view and select the files you want to upload
- Click Open
- Open the Files view from the sidebar
- Select the file(s) you wish to download and click the Download button in the toolbar of the Files view
- Choose the folder where you want the files saved
Orpius can create a wide variety of file types. Common examples include:
- text files (e.g. .txt, .csv)
- code files (e.g. .cs, .py, .js)
- document files (e.g. .md, .html)
- data files (e.g. .json, .xml)
Start a new Chat. Then, for example, you might enter:
"Create a file called test.txt and insert 10 city names."
Orpius will create a new file named test.txt containing the 10 city names and save it in your isolated storage directory.
Every Orpius space is backed by a Git repository. When Orpius or a user changes files in the workspace, those changes are committed automatically.
You do not need to know Git or manage commits yourself. Orpius manages the repository in the background and gives agents access to the history when they need it.
This means you can ask Orpius questions about that history: For example:
User:
"When was the ledger.csv file last changed and what was changed?"
Orpius:
"The ledger.csv file was last changed on August 27, 2026, at 11:58:52 UTC (by the AI agent Nyx as part of the receiptProcessing operation). What was changed: A new row was added to the ledger for a receipt (1005-receipt.jpg): • Filename: 1005-receipt.jpg • Date: 08/15/2017 • Item: Draft Blackhouse, Cowboy 16oz Ribeye, Make It Blue, Add Lobster, CK Manhattan, Whistle Pig Rye 10yr, Duke 16oz Top Sirloin, Make It Blue • Price: 167.00 • Tax: 12.94 • Total: 179.94 • Category: Meals & Entertainment"
Orpius can use the Git history to determine not only what changed, but when it changed, who or what made the change, and the work that caused it.
More importantly, you can ask Orpius to use that history to restore the workspace or individual files to an earlier state.
You do not need to find a commit or know anything about Git. You can describe the point you want to return to in ordinary language.
For example:
"Change the website back to how it was before 22 August."
or
"Restore the files to the state they were in yesterday morning."
or
"Undo the changes you just made."
or
"The application was working before today's changes. Put it back to that state."
Orpius can inspect the history, and restore the relevant files.
Because the history itself is retained, going back does not mean losing everything that happened afterwards. You can inspect those later changes or ask Orpius to restore them again.
For example, you can say:
"Actually, put it back to how it was before we reverted it."
This gives you a workspace that can evolve freely while remaining traceable and reversible. You can let Orpius make substantial changes knowing that previous states remain available if you need to understand what happened, undo a change or return to an earlier point in time.
Orpius can create and host web pages directly from your workspace and make them available through a web address.
Each Orpius Space has a dedicated Web folder. Anything placed in this folder is automatically published by Orpius. This makes it easy for an agent to create a web page, dashboard or lightweight application and make it immediately available without requiring you to set up a separate web server or hosting service.
For example, you could ask:
"Create a simple dashboard from the data in sales.json."
Or:
"Create an interactive HTML worksheet for practising French."
Orpius will create the required files in the Web folder and make them available automatically.
The main published page is normally index.html.
You can find the link to this page from the top navigation bar in the Orpius Console. Where your Space name is shown, select the expand button to reveal the published web link.
You can also ask Orpius directly for the link to a page it has created.
For example:
"Give me the link to the sales dashboard."
At present, content in the Web folder is published automatically.
We plan to extend this with permission-based publishing, allowing you to control who can access published content, for example:
- members of the Space only
- selected users
- publicly accessible pages
This will allow the same publishing capability to be used for both internal applications and information that is intended to be shared publicly.
Email provides another way to work with Orpius without opening the Console.
Behind the scenes, email works through Operations. Each Operation has its own generated email address, so sending an email to that address invokes the Operation.
This means you can create different email addresses for different kinds of work, with each one having its own instructions, agent and permitted tools.
Orpius only accepts messages from authorised email addresses and verifies that the sender is genuine, helping protect against spoofed messages. Messages from other addresses are rejected and never reach the agent.
The email address itself therefore does not need to be treated like a password or secret. Simply knowing the address is not enough to use the Operation.
Any work started by email is also limited to the tools and permissions you have enabled for that Operation.
For example, you might create an Operation called AskFile with simple instructions such as:
"Answer the user's question using the information contained in the file they specify.
If no file is specified, determine which file is most likely relevant based on the question and your knowledge of the files available in the Space.
If there is genuine ambiguity about which file should be used, or any ambiguity in the user's request, use the Dialog plugin to ask the user to clarify before answering.
Base your answer only on information contained in the selected file. Do not invent, infer from outside knowledge, or supplement the answer with information from other sources.
If the file does not contain enough information to answer the question, explain what information is missing."
You can then select the tools the Operation will use. For this Operation, enable CodeExecution so that Orpius can access and analyse files or perform calculations when answering questions, and Dialog so that the agent can ask you or your team members qualifying questions when clarification is needed.
You can also enable Git if you want the agent to provide insights into a file's history, and Memory if you want it to retain information relevant to the task.
Once the Operation is saved, you can find its generated email address at the bottom of the Operation configuration page. You can then send questions to that address in much the same way as you would through Chat. The file you want the agent to work with can already be stored in the Space, or you can simply attach it to the email along with your question.
When you receive a response, you will see that the message has a different reply-to email address. Replies within this email thread remain part of the conversation context sent to the LLM. For unrelated requests, or if you want to minimise token usage, it is therefore best to start a new email.
The full generated email address is not intended to be memorised. The recognisable part is the Operation name, which is included in the address so that you can easily identify its purpose.
For example, suppose you have a file containing your current property listings, either already in the Space or attached to an email to the AskFile Operation, and ask:
"Do we have anything suitable for an older couple who want to downsize? They are looking for properties in Fribourg."
Because the Operation has access to CodeExecution, Orpius can inspect and analyse the file and answer the question based on the information it contains.
An Operation can also be configured for a specific business process.
For example, you might create an Operation called ReceiptProcessing and provide instructions describing how scanned receipts should be handled.
Once that Operation has been configured, you can simply send or forward receipt images to its email address.
You do not need to explain what should happen each time. The Operation already contains the instructions and tools required to carry out the work.
In this case, the email may contain nothing more than the receipt images themselves.
This makes email useful for repetitive work because the process is configured once and the sender only needs to provide the new information.
The capabilities available when an email is processed depend on the tools enabled for the Operation.
These are selected when configuring the Operation.
For example:
- A general question Operation might use Git and CodeExecution.
- A receipt-processing Operation might use Image Analysis, CodeExecution and Git.
- An Operation that needs input from other people might also be given access to Dialog.
This allows each email address to expose only the capabilities required for its purpose.
If the Dialog tool is enabled for the Operation, Orpius can also involve other members of the Space while carrying out work started by email.
For example, you might send:
"Ask Sarah for her view on the supplier's revised terms, consider her response together with the attached proposal, and email me your recommendation."
Orpius can contact Sarah, wait for her response, continue the work using the information she provides, and then send the result back to you.
This means an email can do more than trigger a simple request and response. It can start a longer-running piece of work involving tools, files, other people and further decisions.
We will look at the Dialog tool in more deteail in the next section.
Email conversations retain context in much the same way as Chat.
When you receive a response or a question from Orpius, you will see that the message has a different reply-to email address. When you reply to that message, the previous messages in the thread remain part of the conversation context. This means you can ask follow-up questions without repeating information from earlier messages.
For unrelated work, start a new email rather than continuing an existing thread. This gives the new request a clean context and avoids unnecessarily increasing the amount of previous conversation sent to the language model.
Orpius can carry out work in the background, and sometimes it may need input from a person before it can continue.
The Dialog tool allows an agent to contact you or another member of the team and ask for that input.
For example, you might forward a request from a customer and instruct the AI agent:
“Prepare the customer proposal. If you are unsure about the pricing, ask Sarah. Send the completed proposal to me for approval before it is sent to the customer.”
The agent can carry out the work until it reaches the point where Sarah's input is needed, ask her the question, and continue once she responds.
Dialogs can also be part of the normal work itself. In the earlier example where the agent sends Charlie an interactive maths worksheet every second day, the scheduled work can use a Dialog to send Charlie the worksheet and wait for his response. Once he sends it back, the agent can grade his answers and continue with the rest of the work.
The Dialog can be used to:
- ask for missing information
- clarify something that should not be assumed
- request a decision, confirmation or approval before taking an action
- involve another member of the team
- wait for a response that is part of the work itself
- continue a longer conversation while the surrounding work remains in progress
The important point is that work does not need to fail or end simply because another person needs to be involved. The agent can wait for a response and continue afterwards.
Our aim with Orpius is for people and AI to work together as naturally as possible. You should not have to anticipate every possible decision or exception in advance. If something is unclear, or if the work needs something from another person, the AI can ask the right person, wait for a response, and then continue.
A Notification is used when Orpius needs to tell someone something. Notifications are sent by email from a no-reply address and do not expect a response.
A Dialog is used when Orpius needs a response. For example:
"Tell Robert that the report is ready."
can be handled as a notification without the means or need for a response.
Whereas:
"Ask Robert whether the figures have been approved before publishing the report."
requires a Dialog because the agent needs Robert's answer before deciding what to do next.
Dialogs allow people to remain part of automated work without requiring them to supervise every step.
An organization can contain multiple spaces, and each space can have as many users as needed.
Orpius provides team collaboration across time zones; agents are aware of the time zone of each team member. This allows agents to coordinate activities based on expected working hours for example. Agents with access to the Notifier tool gain this team awareness; allowing them to notify other team members during an activity.
This same awareness also enables Orpius to make informed decisions about who is best placed to action time-critical activities, such as assigning urgent requests or service tasks to the most appropriate, available team member in a services-based environment.
flowchart TB
Agent["Agent (with Notifier)"] --> Team["Team Directory (time-zones)"]
Agent --> Notify["Notifications / Email"]
Team --> Rules["Rules (working hours, role)"]
Rules --> Notify
You can use team awareness within the chat interface by asking, "Who is on my team?" Orpius will respond with an up-to-date list of your team members.
Alternatively, you might say, "Please thank John for completing the quarterly report." Orpius will automatically send John both an email and an in-app notification on your behalf.
Team awareness also applies in non-interactive scenarios such as scheduled activities, event activities, or in operations (where the Notifier tool is enabled). For example, when an event activity is created or updated, Orpius can automatically identify relevant team members-based on predefined rules or business logic-and notify them through email or in-app messages. This ensures that key stakeholders remain informed and that operational communication occurs seamlessly, without the need for manual intervention.
Users with the space role of Administrator or Owner can invite other users to a space, either from within or outside the organization.
Each member is assigned a role within the space that determines that user's permissions:
- Participant – minimal access. The user can receive notifications and perform tasks.
- Editor – includes all Participant privileges, plus the ability to modify content and manage tasks in the space.
- Administrator – can add and remove non-administrator members, and configure space settings.
- Owner – full control over the space, including deleting it or transferring ownership (a planned feature).
- Open the Team view from the sidebar
- Select the '+ Add New Team Member' button in the toolbar of the Team view
- Search for the team member you wish to add
- Select the desired permission, optionally enter a message for the user
- Send Invitation
- Sign in to the Orpius Console and select any Space (invitations are visible in all your spaces).
- Open the Notification View - You will see an invitation notification to a Space you've been invited to join.
- Accept the invitation
- Sign in again to access the Organization View, where you can see the new Space.
System owners can configure the following limits that control user access across the organization:
- Set the maximum number of users in an organization.
- Set the maximum number of administrators in an organization.
- Restrict new users to having an email address within the organization by configuring a regular expression.
For example, to restrict new users to email addresses within the domain
yourcompany.com,yourcompany.org, oryourcompany.net, you could use the following regular expression:^[A-Za-z0-9._%+-]+@yourcompany\.(com|org|net)$
System Owners can manage key configuration options and restrictions in the System Settings view within the Orpius Console.
Key areas include:
-
Email Server - Change the settings you configured when first setting up the system.
-
SMTP Event Server Port – Specify the port used by the Orpius system SMTP server for incoming email notification.
-
Organization – Set the maximum number of users and administrators allowed in an organization.
-
Application - Restrict new users to those from within your organization. Set limits for cache item lifespan, refresh token lifespan, and timeouts.
-
Inferencing – Manage limits on inferencing operations.
-
Workflow – Control limits related to workflow execution and activity processing.
You are now ready to begin working with Orpius in your own environment.
For more information on extending Orpius, developing custom tools, or integrating it into your applications, refer to the Development Guides. If you have questions, ideas, or wish to discuss your implementation with others, visit the Orpius SDK Discussions.
Tip: Treat each new agent or integration as an iterative experiment; adjust its persona, tools, and model configuration until it performs tasks reliably and efficiently.