Orkas User Guide
Start with a task, then learn each core feature through the controls you can see in the desktop app. Privacy, security, and FAQ are collected separately.
# Tell Orkas what you want to do
Open a new task and describe the result you want in one or two sentences. If you have several tasks, list them one per line. Orkas will help break them down and ask for important missing details.
For example:
- Summarize this report and list the decisions I need to make.
- Compare these three options and recommend one for my budget.
- Turn these notes into a presentation for next week's review.
You can also ask Commander how to use Orkas. For supported requests it can offer a click-to-open shortcut or complete the change through the dedicated workflow; protected or consequential steps still require your action.
# Your first task
A useful request names the result, the source material, the audience or intended use, and any important format, deadline, or approval boundary.
Open Commander
Start a new task from the main conversation area.
Describe the outcome
Say what a successful result looks like and which constraints matter.
Add only relevant context
Attach a file or select an agent, skill, connector, or Library source when the task needs it.
Choose the runtime
Use the model shown in the task input. To add an external CLI agent, use Connect a coding agent on the AI Team page, or the @ agent picker in the composer.
Follow progress
Answer decision, detail, permission, or form requests. A Codex question panel can appear above the message input while work continues: choose or type each answer, then select Send answer. Drafts survive switching tasks. Unanswered cards remain available while the current CLI turn accepts input. Select Cancel to dismiss an unanswered question without sending an answer or stopping the task. Cancelled questions stay closed after switching tasks or reloading. If cancellation fails, your draft is kept for retry. The panel also closes after answering or when the turn ends. The submitted answer stays in the conversation. Send a new message to continue after the turn ends. For Claude Code questions, select the requested choices or enter a custom answer, then confirm.
Review the result
Open or download the output, then ask for a focused revision in the same task when its context still applies.
Queued messages offer Send now when available, Edit, and Cancel. Edit puts the message, attachments, references, and resource chips back in the main input box. Other queued messages wait while replies already in progress continue. Use the check button to save in the same queue position, Escape to keep the original message, or Cancel on its queue row to cancel it without sending. Each completed action restores your previous draft. Edits survive switching tasks and reloading the window; a failed save keeps your text for retry.
Use @ or the recipient panel to choose Agents; selected Agents appear at the top for removal. Panel mentions are inserted at the cursor. An opening @ replaces the current recipient; text before the first @ goes to the current recipient, and later @ mentions start new instructions. Adjacent mentions share the following description. After an accepted send, a single recipient stays selected; multiple recipients return the next message to Commander. A Commander handoff selects its Agent. Temporary delegation keeps the current recipient until an Agent asks for your input; an input form selects its owner. Asking about a form does not submit it. An explicit transfer to Commander selects Commander; a later manual choice takes priority.
# Model setup
Orkas gives you two ways to use chat models: choose an Orkas-managed official model that is ready for your account, or connect a model provider you already use. The choice affects capability, speed, cost, billing, and the route your request takes.
What it gives you
- Orkas built-in models include Orkas-1.5 and Orkas-1.5 Pro. Their current frontier lineup covers DeepSeek V4.1 Flash, GPT-6 models, Claude 5 models, Gemini 3.8 Flash, and Kimi K3; the list shown in Orkas is always authoritative.
- With Bring your own API Key, you can connect your own provider through OAuth or an API key, or add a custom OpenAI-compatible or Anthropic-compatible endpoint with its exact model ID. To use a ChatGPT plan, choose OpenAI Codex and authorize your account; the OpenAI entry uses an API key billed separately from the plan. For a Claude plan, choose Anthropic and authorize your account; its API key option is billed separately.
- Chat models share one task-input selector. Search, image, video, and text-to-speech services are configured separately, while external CLI agents use their own CLI model settings. The shared model control stays visible but disabled when every recipient is an external CLI Agent.
Best for
- Use an official model when you want managed access to current models without setting up a provider key.
- Configure your own provider when you want to use your existing account, billing, endpoint, or a specific model.
- Switch models when a task needs different reasoning, coding, visual, speed, or cost characteristics.
Start here
- Open Account settings > Models. Enable one of the Orkas built-in models, or add and test a provider under Bring your own API Key.
- In a task, open the model control and choose the ready model or saved provider configuration you want to use.
- Configure search, image, video, or text-to-speech in its own group only when the task needs that service.
# Projects
A Project gives a long-running goal one shared workspace, so related tasks begin with the same background instead of rebuilding context in every conversation.
What it gives you
- Keep the goal, stable instructions, preferred output, and Project memory together.
- Reuse the agents, Library sources, and other resources that regularly support the work.
- Organize related tasks, conversations, to-dos, and Project automations in one place.
Best for
- A goal will take several tasks, such as launching a product, running research, or producing content over time.
- Future tasks should follow the same background, rules, preferred output, agents, or reference material.
- Tasks, to-dos, and scheduled automation belong to one ongoing body of work.
Start here
Create or open a Project, state the ongoing goal, then add only the instructions and resources that should apply across its tasks.
- Put rules that should apply across future Project tasks in Goals & rules (up to 4000 characters).
- Put temporary directions in the current task instead.
- Add only the agents and sources that regularly support this Project, then review memory and to-dos as the work changes.
- In Orkas 1.7.0, ask Commander to manage to-dos in an existing Project. In ordinary chat, name the Project; clarify an ambiguous name before changes are saved. This does not move the conversation.
- Creating or editing a to-do does not link a task conversation. After execution starts successfully, open Task conversation on its card to return to the latest execution. A successful new start updates the link; a failed start or a status-only update keeps it unchanged.
Add an existing task to a Project
For a task outside a Project, open its three-dot menu and choose Add to project. Select an existing Project and click Move, or choose New project and confirm its name. The action is disabled while the task is running; wait for it to finish, or stop it and wait for remaining work to finish. History and attachments stay with the task.
Participating agents are selected by default; uncheck any you do not want to add. A Commander-only task has no agent section. Unchecking an agent does not remove an existing Project member.
If some agents cannot be added, the task stays in the Project and successful additions are kept. The message reports the failed count; open the Project to check its members.
Commander can also do this itself in the reply that delivers a result: a recurring request becomes an Automation, and work toward a longer goal gets a new Project with its first to-dos and this conversation filed under it. To undo it, say so in the same conversation or choose Remove from project, the entry a task inside a Project shows in place of Add to project.
Share a Project
As the owner, open Members > Invite members, review the sharing scope, then create and copy the invitation link. Check the displayed member allowance and expiry. Recipients open Orkas from the link and confirm joining with the intended account.
Goals & rules, memory, files, to-dos and their attachments are shared. Tasks and automations stay private. Custom Agents need an explicit Share action; CLI Agents stay private. In shared Projects, locks mark private content. Members can edit any to-do; Auto only processes their own.
Content saves locally before background publication; saving does not confirm delivery to members. Personal cloud sync is separate. Use Refresh at the top right to retrieve updates and retry pending changes. Review Project conflicts before choosing a copy. Invitation links do not wait for uploads. Uploads can resume after interruption or restart; use Pause sync or Retry in Members. While content syncs, members can work with local Agents.
Leaving or being removed keeps a personal copy, removes other members’ Agents and to-dos not assigned to you, and pauses Project automations. Rejoining creates a separate shared Project. The owner’s End sharing stops collaboration for everyone and removes shared cloud data; downloaded copies remain.
# Automation
Automation turns a well-defined instruction into work that runs once later or on a repeating schedule, without you starting the same task manually each time.
What it gives you
- Schedule a one-time run or repeat every few hours, daily, weekly, or monthly, with an optional end date or run-count limit.
- Attach the automation to a Project so each run can use its stable context and resources.
- Use configured models and connectors at run time, review earlier results, and pause future runs without deleting them.
Best for
- You need a report, summary, collection, or review every few hours, daily, weekly, or monthly.
- A recurring check should use the same Project context or connected service every time.
- A one-time task should run at a specific future time instead of being remembered manually.
Start here
Open Auto, write the instruction as it should be understood at run time, choose the schedule, optional end condition, and optional Project, select the device that should run it, then save and enable it. Review the first result before relying on future runs.
# Agents
An agent is a reusable specialist that owns a type of work with a defined role, method, quality bar, capabilities, and role-specific memory.
What it gives you
- Turn recurring professional expectations into a specialist you can select instead of restating them.
- Give the specialist a workflow, required inputs, delivery standards, memory, and access to relevant capabilities.
- Use an Orkas-run agent or connect a supported local CLI agent such as Codex, Claude Code, or OpenCode.
Best for
- You repeatedly need the same specialist perspective, such as research, product design, data analysis, or content review.
- The work should follow stable quality standards, use specific capabilities, or remember role-related context.
- You want a local external CLI such as Codex, Claude Code, or OpenCode to own a task.
Start here
- Open AI Team and choose Create agent to define an Orkas agent, then review its workflow, inputs, standards, and memory.
- Select an agent in the task input when that specialist should own the work. Add only agents that contribute to the requested result.
- To use Codex, Claude Code, OpenCode, or another supported CLI, choose Connect a coding agent on the AI Team page after installing and signing in to that CLI.
- In the external agent details, use Runtime settings to choose supported model, thinking, and permission overrides. Ask for permission forwards native CLI approval requests through the shared Orkas confirmation dialog, which shows the CLI action or selected path and returns the decision to the CLI. OpenCode uses fixed Full access and hides the permission selector.
- For Claude Code, Codex, and OpenCode, keep the workspace default or choose a project directory. Ask to switch projects during a task to choose another existing folder.
- During a task, Claude Code, Codex, OpenCode, Hermes, and OpenClaw can use the built-in Browser for that conversation only. You can switch to other Orkas pages while the agent continues working in its task browser. Other conversations and external browser windows are outside its access. In Task Details > Browser, you can interact with the page directly. AI page actions pause while you interact and become available again after 10 seconds without input, once held keys, dragging, or input-method composition have ended. The agent can read ordinary form values, fill and submit fields including passwords, verification codes and card details, and upload files from the task workspace or attachments. Sensitive field values are never returned to the model. Task downloads need no separate site approval. Uploads and downloads have no browser count or size quota; website limits apply. Choose Let AI continue for immediate handback after finishing your input. Allow website permissions or select a screen when prompted. Reset site permissions in the browser toolbar clears that site’s choices without reloading the form. Complete CAPTCHA or other site-required checks when prompted; automatic control recovery does not restart a stopped task. AI uploads use file paths and ordinary downloads save to task attachments without a file dialog. Attach external files to the conversation. Website native file-system pickers are cancelled during AI control; use the website manually if it offers no ordinary upload or download. AI can allow or deny keeping the screen awake for the current request. Other website permissions still require your choice.
If a CLI is below the minimum supported version, upgrade it from the connection panel, Agent details, or the named CLI button at the bottom of the task error bubble. Progress appears on the button; the result appears beside it. Retry the task after a successful upgrade. Supported versions adapt automatically; if an explicitly selected model is unavailable, change it in Runtime settings.
For an Orkas-run agent, ask Commander or the agent's edit conversation to save the available skills it should use by default. After a successful edit, the list stays across tasks and restarts. These defaults make skills available for use when needed; they do not run automatically, load all their instructions at once, or prevent discovery of other eligible shared skills. Selecting a skill for one task does not change the saved list. External CLI agents use their own skill setup.
For audio-only work, select VoiceStudio in AI Team and provide a script or recording. Ask for narration, transcription, cuts, or mixing with supplied music. Speech generation uses your configured text-to-speech service and sends the script online; transcription and editing use bundled components without first-use downloads. Keep the saved project and audio together for later paragraph or mix changes. Repair or update Orkas if a required component is missing.
# Skills
A skill packages how to do a repeatable job—the steps, checks, references, and expected result—so the same method can be reused by different tasks and agents.
What it gives you
- Preserve a proven method, checklist, template, and output rules as one reusable workflow.
- Apply the same method across tasks and agents without creating another specialist identity.
- Create a skill manually, from a URL or folder, import a local Skill ZIP, or install an existing one from Marketplace.
Best for
- The same steps, template, checks, or output format should be reused frequently.
- Several agents or tasks should follow one shared operating method.
- You want to turn an existing guide, URL, or local folder into a reusable workflow.
Start here
- Open Skills and choose Create skill to start manually, from a URL, or from a folder. Finish its edit conversation before relying on it.
- Select the skill in a task and describe the outcome normally, including any inputs that workflow needs.
- Browse Marketplace when you want an existing workflow instead of creating one from scratch.
- To pause a skill, open its card's ⋯ menu in Skills and choose Disable; choose Delete to remove one you created, and uninstall Marketplace skills from Marketplace.
# Connectors
A connector gives Orkas authorized access to an external service, so a task can use current service data or perform allowed actions without repeatedly exporting files.
What it gives you
- Read live information from the connected account or workspace when the task needs it.
- Create, update, send, or perform other supported actions within the access you authorize.
- Connect a catalog service through its authorization flow or add a trusted custom MCP server.
Best for
- The task needs live information that changes in an external service.
- Orkas should create, update, send, or otherwise act in that service with your authorization.
- A repeated workflow should use the same connected workspace or account without exporting files each time.
Start here
- Open Connectors or ask Commander in the current task to connect or reconnect a service. Simple authorization only needs a connection entry and your consent. For extra configuration, Commander uses the setup guide and browser assistance; Ask Commander in the setup panel starts a separate assistance task. Protected field values are not sent with the request. Confirm the connected state afterward. For a connected Feishu/Lark, DingTalk, WeCom or Xero service, open the card’s three-dot menu and choose Reauthorize when needed. Your connection and selected capabilities are kept; return to the task afterward.
- Not connected does not mean unsupported: check the available catalog first. For a trusted server outside the catalog, use Add MCP server and review any remote address or local command before connecting.
- Select the connector only in tasks that need it and clearly state what Orkas may read or do.
In Orkas 1.7.0, connector actions use Account settings > General > Local operation permissions, including calls from external CLI agents. Recognized reads and ordinary edits need no confirmation. Cautious and Standard ask before sensitive or unclassified actions; Trusted runs available connector actions without confirmation. Prohibited actions remain unavailable. Expand View details to inspect the operation and parameters. Allow once approves only the current operation; Allow for this task approves all subsequent operations for this connector account, including deletion, until the task ends or stops. Reconnecting clears that approval; global permissions stay unchanged.
# Library
Library turns reference documents and stable material into reusable knowledge. Once processing finishes, Orkas can retrieve the most relevant passages for a question or task instead of making you upload and search the same files again.
What it gives you
- Ask quick, source-based questions and get answers grounded in processed policies, manuals, research, notes, or product material.
- Compare, summarize, extract, or write from a selected collection without manually locating every passage.
- Reuse the same sources across later tasks, Projects, and supported synced devices.
Best for
- You want quick, source-based Q&A across policies, manuals, research, product material, meeting notes, or other reference documents.
- Several tasks need to compare, summarize, extract, or write from the same collection of sources.
- The material should remain available for later tasks or on another synced device instead of being a one-time attachment.
Start here
- Open Library, add supported sources, give them recognizable names, and wait for processing to finish.
- In Commander or a Project task, select only the Library sources relevant to the current question.
- Ask a direct question or describe the result you want. When the answer must stay within the material, explicitly ask Orkas to use only the selected sources.
# Apps
Apps turns eligible interactive task results into reusable tools you can launch again without finding and reopening the original conversation first.
What it gives you
- Apps > Create: choose Local app, describe your idea, then create, review and save it.
- Open and use a saved app directly after the task that created it has finished.
- Choose Apps > Edit to revise an app in a new task. Choose Update original app to keep its identity, or Save new app for an independent copy. If the original changed or was deleted, reopen it to edit or save a new app.
Best for
- Orkas creates an interactive dashboard, calculator, form, tracker, or other reusable tool.
- You want a result to remain easy to launch after the task is finished.
- Choose Apps > Edit to revise an app in a new task. Choose Update original app to keep its identity, or Save new app for an independent copy. If the original changed or was deleted, reopen it to edit or save a new app.
Start here
Choose Apps > Edit to revise an app in a new task. Choose Update original app to keep its identity, or Save new app for an independent copy. If the original changed or was deleted, reopen it to edit or save a new app.
These host capabilities are available only to local apps: Apps built for Orkas can use the configured model, selected files, app storage, global Library and enabled connectors when requested and permitted. Model calls may incur charges but do not ask for separate app consent. Sensitive connector actions follow your operation permission mode; Trusted does not ask. Allow for this use lasts until this app closes, for that connector account and operation type. Reopening asks again when needed. File export creates a new file. Each app has a private sandbox for data and files. Apps using cloud storage can sync it when the same account enables sync on each device; caches stay local. Saving does not mean upload is complete. Older app data stays local unless explicitly migrated, and saved copies remain independent. Close and reopen after changing accounts or model setup. Older apps and standalone HTML exports do not gain these abilities automatically.
Published app menus offer Update publication when the source is on this device, and Unpublish. Delete is hidden until unpublishing completes, including for suspended apps. Unpublishing permanently deletes online data; local code and data remain. Published files and online data share your account cloud storage with sync and project collaboration. Publication details show file, database and total usage. Deleting records frees space only after storage is reclaimed.
Apps can load external scripts and resources and call external services directly. These services receive the data the app sends; direct calls do not use connector permission dialogs. External scripts have the app’s capabilities. Service authentication and browser cross-origin rules still apply.
# Cloud sync
Cloud sync keeps supported Orkas data available on computers signed in to the same account, so ongoing work can continue without manual export and import.
What it gives you
- Carry supported tasks, Projects, agents, skills, and Library sources across signed-in devices.
- Continue an ongoing workflow from another computer after its changes finish syncing.
- Keep device-local data, including model API keys and task attachments, outside cloud sync.
Best for
- You use Orkas on more than one computer and want supported work to follow your account.
- A task, Project, agent, skill, or Library source created on one device should be available on another.
- You want to continue an ongoing workflow on another signed-in device without exporting and importing it manually.
Start here
Open Account settings > Data, enable cloud sync on each device that should participate, keep Orkas open while the first changes upload, and wait for sync to finish before editing the same item elsewhere.
Know before relying on it
- Keep Orkas open and connected until a large change finishes syncing, and avoid editing the same item on another device before it completes.
- Task attachments do not sync with their task. Add a supported file to Library when it should be reusable on another synced device.
- Model API keys stay on the device where they were configured and are not cloud-synced.
- Disabling sync on one device stops future synchronization there; it does not delete cloud data.
Clean up task history
In Account settings > Data > Clean up task history, choose 7, 14, 30, 60, 90 or 180 days (default 30). Open View and select projects or individual tasks, then confirm cleanup on the same page. Nothing is selected initially. Running or queued tasks are stopped automatically when you confirm cleanup. You can view a task’s conversation from this list, then return to continue cleanup.
Filter all task history by age, then clean up by project or task.
History, attachments and embedded results move to the local recycle bin, where Restore can recover them. Enabled cloud sync also deletes tasks on other devices. Space is freed only after emptying the recycle bin. Pinned and unread tasks, drafts and automation runs can be selected. Unsent drafts are deleted; automation settings are kept.
# Privacy and security
Orkas is local-first, while models, connectors, external CLI agents, optional sync, and sharing can send or store the data needed for those features. Model API keys stay on the configured device, and task attachments do not sync with their task. Review the active account, selected services, permission mode, and confirmation text before sensitive work. See Security & Trust for current storage, encryption, network, and sharing boundaries.
# FAQ
How do I start a task in Orkas?
Open a new task and describe the result you want. You can list several tasks one per line. Add only the files or resources the work needs, then follow the visible status until the result is ready.
When should I use a task attachment, Library, or Project?
Use a task attachment for one conversation, Library for material you want to reuse, and a Project when multiple tasks share instructions, sources, memory, or automations.
What should I check when a task will not run?
Check the visible task state first. You can ask Commander to inspect supported sanitized app status and offer a shortcut to the relevant screen. Answer any waiting question, restore an unavailable resource, and retry only after checking whether an external action already succeeded.
Where do I manage models, permissions, memory, sync, and account data?
Open the account entry at the bottom of the sidebar and choose Account settings. Use Account for Plan and Credits left, Data for Memory and sync, Models for chat and service setup, and General for permissions, notifications, language, and updates.