Merge pull request #898 from andrewyng/docs/desktop-getting-started

Add Desktop App docs
This commit is contained in:
Rohit Prasad
2026-11-13 16:34:18 -08:00
committed by GitHub
48 changed files with 1468 additions and 41 deletions
+2
View File
@@ -1,6 +1,8 @@
node_modules
dist/
dist-desktop/
.astro/
src/content/docs/
src/content/desktop/
public/reference/
public/examples/
+25 -1
View File
@@ -1,4 +1,4 @@
# OpenWorker SDK documentation site
# OpenWorker documentation site
Plain Markdown in `docs/harness/` is authoritative and readable on GitHub.
`pages.json` chooses the public navigation; `scripts/prepare.mjs` adds site-only
@@ -21,6 +21,30 @@ shared custom Astro layout instead of Starlight presentation components. Pagefin
indexes the public guides in `pages.json` after the static build; preview and error pages are
excluded. The site does not require a private repository to build.
## Desktop App preview
Desktop user guides live in `docs/desktop/guides/`. `desktop-pages.json` is their
explicit publication manifest. They reuse Studio, with their own navigation,
content directory, output and search index; the normal build remains the SDK.
```sh
npm run desktop:build
npm run desktop:preview -- --host 127.0.0.1 --port 4330
# http://127.0.0.1:4330/docs/desktop/
python3 scripts/verify-built.py dist-desktop /docs/desktop desktop
```
The Desktop scripts above use POSIX environment assignment. On other shells,
set `OW_DOCS_PRODUCT=desktop`, then run `npm run prepare-content`, `npx astro build`
and `npx pagefind --site dist-desktop --root-selector "[data-pagefind-body]"`.
Keep that variable set for `npm run preview` too. Build products sequentially;
the generated public asset directory is refreshed for the selected product.
The initial Desktop pages are a local, noindex preview. SDK design-comparison
routes and source bundles are excluded from the Desktop build. Publication is a
separate step: the existing hosting preparation and router target `/docs/sdk/`
and must not be used to deploy Desktop output without a reviewed hosting change.
## Language tabs in plain Markdown
Wrap alternatives with HTML-comment markers and ordinary headings:
+5 -1
View File
@@ -1,8 +1,12 @@
import {defineConfig} from 'astro/config';
import sitemap from '@astrojs/sitemap';
import {docsProduct} from './product.mjs';
const product=docsProduct();
export default defineConfig({
site:'https://openworker.com',
base:process.env.OW_DOCS_BASE??'/docs/sdk',
base:product.base,
outDir:product.id==='desktop'?'./dist-desktop':'./dist',
cacheDir:product.id==='desktop'?'./node_modules/.astro-desktop':'./node_modules/.astro',
devToolbar:{enabled:false},
integrations:[sitemap({filter:url=>!url.includes('/previews/')})],
});
+86
View File
@@ -0,0 +1,86 @@
[
{
"source": "docs/desktop/guides/index.md",
"slug": "index"
},
{
"source": "docs/desktop/guides/first-task.md",
"slug": "first-task"
},
{
"source": "docs/desktop/guides/how-it-works.md",
"slug": "how-it-works"
},
{
"source": "docs/desktop/guides/models.md",
"slug": "models"
},
{
"source": "docs/desktop/guides/local-models.md",
"slug": "local-models"
},
{
"source": "docs/desktop/guides/voice.md",
"slug": "voice"
},
{
"source": "docs/desktop/guides/coworkers.md",
"slug": "coworkers"
},
{
"source": "docs/desktop/guides/coding.md",
"slug": "coding"
},
{
"source": "docs/desktop/guides/sessions-files.md",
"slug": "sessions-files"
},
{
"source": "docs/desktop/guides/connectors.md",
"slug": "connectors"
},
{
"source": "docs/desktop/guides/skills-memory.md",
"slug": "skills-memory"
},
{
"source": "docs/desktop/guides/automations.md",
"slug": "automations"
},
{
"source": "docs/desktop/guides/security.md",
"slug": "security"
},
{
"source": "docs/desktop/guides/machines.md",
"slug": "machines"
},
{
"source": "docs/desktop/guides/run-location.md",
"slug": "run-location"
},
{
"source": "docs/desktop/guides/sandbox.md",
"slug": "sandbox"
},
{
"source": "docs/desktop/guides/native-sandbox.md",
"slug": "native-sandbox"
},
{
"source": "docs/desktop/guides/openshell.md",
"slug": "openshell"
},
{
"source": "docs/desktop/guides/approvals.md",
"slug": "approvals"
},
{
"source": "docs/desktop/guides/privacy.md",
"slug": "privacy"
},
{
"source": "docs/desktop/guides/troubleshooting.md",
"slug": "troubleshooting"
}
]
+2
View File
@@ -7,6 +7,8 @@
"dev": "npm run prepare-content && astro dev",
"build": "npm run prepare-content && astro build && pagefind --site dist --root-selector \"[data-pagefind-body]\"",
"preview": "astro preview",
"desktop:build": "OW_DOCS_PRODUCT=desktop npm run prepare-content && OW_DOCS_PRODUCT=desktop astro build && pagefind --site dist-desktop --root-selector \"[data-pagefind-body]\"",
"desktop:preview": "OW_DOCS_PRODUCT=desktop astro preview",
"test": "node --test scripts/*.test.mjs"
},
"dependencies": {
+21
View File
@@ -0,0 +1,21 @@
import sdkPages from './pages.json' with {type:'json'};
import desktopPages from './desktop-pages.json' with {type:'json'};
import {navigation as sdkNavigation} from './src/lib/navigation.mjs';
import {desktopNavigation} from './src/lib/desktop-navigation.mjs';
// An explicit manifest per product keeps private notes and unreviewed pages out
// of both the static output and search. SDK remains the default build target.
export function docsProduct(env=process.env) {
const id=env.OW_DOCS_PRODUCT??'sdk';
if(!['sdk','desktop'].includes(id))throw Error(`Unknown docs product: ${id}`);
const desktop=id==='desktop';
return {
id,
label:desktop?'Desktop App':'Harness SDK',
title:desktop?'OpenWorker Desktop':'OpenWorker SDK',
base:env.OW_DOCS_BASE??`/docs/${id}`,
content:desktop?'desktop':'docs',
pages:desktop?desktopPages:sdkPages,
navigation:desktop?desktopNavigation:sdkNavigation,
};
}
+23 -10
View File
@@ -4,22 +4,35 @@ import {dirname,resolve,join,posix} from 'node:path';
import {fileURLToPath} from 'node:url';
import {renderCodeTabs} from './code-tabs.mjs';
import {writeSources,renderSourceButton} from './source-examples.mjs';
import {docsProduct} from '../product.mjs';
const site=resolve(dirname(fileURLToPath(import.meta.url)),'..'),root=resolve(site,'..');
const pages=JSON.parse(readFileSync(join(site,'pages.json'),'utf8'));
const output=join(site,'src/content/docs'),base=(process.env.OW_DOCS_BASE??'/docs/sdk').replace(/\/$/,'');
const product=docsProduct(),pages=product.pages;
const output=join(site,'src/content',product.content),base=product.base.replace(/\/$/,'');
// Remove previously generated reference pages so an incremental build cannot
// accidentally republish archived design/specification material.
rmSync(join(site,'public/reference'),{recursive:true,force:true});
const images=new Map(['pdf-notes'].map(name=>[
const images=product.id==='desktop'?new Map([
['docs/desktop/guides/images/notes-to-brief.svg','examples/notes-to-brief.svg'],
['docs/desktop/samples/meeting-notes.zip','examples/meeting-notes.zip'],
]):new Map(['pdf-notes'].map(name=>[
`docs/harness/guides/images/${name}.jpg`, `examples/${name}.jpg`
]));
images.set('docs/harness/assets/architecture.svg', 'examples/architecture.svg');
images.set('docs/harness/guides/images/session-tracing.jpg', 'examples/session-tracing.jpg');
if(product.id==='sdk') {
images.set('docs/harness/assets/architecture.svg', 'examples/architecture.svg');
images.set('docs/harness/guides/images/session-tracing.jpg', 'examples/session-tracing.jpg');
} else {
for(const name of ['models','voice','machines','coworkers','sandbox','auto-approve'])
images.set(`docs/desktop/guides/images/${name}.jpg`, `examples/desktop/${name}.jpg`);
}
// This directory is generated. Clear the other product's assets as well so
// switching build targets cannot leak SDK source bundles into Desktop output.
rmSync(join(site,'public/examples'),{recursive:true,force:true});
mkdirSync(join(site,'public/examples'),{recursive:true});
rmSync(join(site,'public/examples/code-atlas.png'),{force:true});
rmSync(join(site,'public/examples/pdf-notes.png'),{force:true});
for(const [source,destination] of images) copyFileSync(join(root,source),join(site,'public',destination));
writeSources(root,join(site,'public'));
for(const [source,destination] of images) {
mkdirSync(dirname(join(site,'public',destination)),{recursive:true});
copyFileSync(join(root,source),join(site,'public',destination));
}
if(product.id==='sdk')writeSources(root,join(site,'public'));
const route=new Map(pages.map(p=>[p.source,`${base}/${p.slug==='index'?'':p.slug+'/'}`]));
rmSync(output,{recursive:true,force:true});mkdirSync(output,{recursive:true});
for(const page of pages) {
@@ -35,4 +48,4 @@ for(const page of pages) {
raw=renderSourceButton(renderCodeTabs(raw,page.slug),base);
writeFileSync(join(output,page.slug+'.md'),`---\ntitle: ${JSON.stringify(title[1])}\n---\n\n${raw}`);
}
console.log(`Prepared ${pages.length} SDK pages from repository Markdown`);
console.log(`Prepared ${pages.length} ${product.label} pages from repository Markdown`);
+39
View File
@@ -0,0 +1,39 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {readFileSync,existsSync} from 'node:fs';
import {resolve,dirname} from 'node:path';
import {fileURLToPath} from 'node:url';
import {docsProduct} from '../product.mjs';
const root=resolve(dirname(fileURLToPath(import.meta.url)),'../..');
test('Desktop and SDK have explicit separate manifests and navigation',()=>{
const sdk=docsProduct({}),desktop=docsProduct({OW_DOCS_PRODUCT:'desktop'});
assert.equal(sdk.base,'/docs/sdk');
assert.equal(desktop.base,'/docs/desktop');
assert.notEqual(sdk.content,desktop.content);
const required=['index','first-task','how-it-works','models','local-models','voice','coworkers','coding','security','machines','run-location','sandbox','native-sandbox','openshell','approvals','privacy','troubleshooting'];
for(const slug of required)assert.ok(desktop.pages.some(page=>page.slug===slug),slug);
for(const product of [sdk,desktop]) {
const slugs=new Set(product.pages.map(page=>page.slug==='index'?'':page.slug));
assert.equal(slugs.size,product.pages.length,'Duplicate page routes');
for(const section of product.navigation)for(const [,slug]of section.links)assert.ok(slugs.has(slug),slug);
for(const page of product.pages) {
assert.ok(page.source.startsWith(`docs/${product.id==='sdk'?'harness':'desktop'}/guides/`));
assert.ok(existsSync(resolve(root,page.source)));
assert.ok(!/ledger|journal|evidence|\.env/i.test(page.source));
}
}
assert.equal(docsProduct({OW_DOCS_PRODUCT:'desktop',OW_DOCS_BASE:'/preview/desktop'}).base,'/preview/desktop');
assert.throws(()=>docsProduct({OW_DOCS_PRODUCT:'unknown'}),/Unknown docs product/);
});
test('first-task sample and UI instructions agree with the app source',()=>{
const read=path=>readFileSync(resolve(root,path),'utf8');
const ui=JSON.parse(read('surfaces/gui/src/locales/en.json'));
const guide=read('docs/desktop/guides/first-task.md');
for(const label of [ui.intro.task_folder_title,ui.access.allow_writes,ui.composer.mode.interactive,ui.nav.settings])assert.ok(guide.includes(label),label);
const samples=['01-kickoff.md','02-design-review.md','03-launch-check.md'].map(name=>read(`docs/desktop/samples/meeting-notes/${name}`)).join('\n');
for(const phrase of ['read-only preview','Priya','Thursday','Sam','Friday','support handoff','not confirmed'])assert.ok(samples.includes(phrase),phrase);
assert.ok(guide.includes('../samples/meeting-notes.zip'));
assert.ok(!/0\.\d+\.\d+|beta\.\d+/i.test(guide),'Keep release numbers out of the walkthrough');
});
+15 -3
View File
@@ -7,7 +7,9 @@ site = Path(__file__).resolve().parent.parent
root = site.parent
output = Path(sys.argv[1]).resolve()
base = sys.argv[2].rstrip('/')
pages = json.loads((site/'pages.json').read_text())
product = sys.argv[3] if len(sys.argv)>3 else 'sdk'
assert product in ('sdk','desktop'), product
pages = json.loads((site/('desktop-pages.json' if product=='desktop' else 'pages.json')).read_text())
class Page(HTMLParser):
def __init__(self, html):
super().__init__(); self.ids=set(); self.links=[]; self.sources=[]; self.indexed=False; self.studio=False; self.pres=0
@@ -27,7 +29,7 @@ for p in pages:
assert page.studio and page.indexed, file
# Source drawer has one extra pre; all Markdown code fences remain present.
fences=len(re.findall(r'^```[^\n]*\n[\s\S]*?^```', (root/p['source']).read_text(), re.M))
assert page.pres==fences+(p['slug'] in ('desktop','server')), (file,page.pres,fences)
assert page.pres==fences+(product=='sdk' and p['slug'] in ('desktop','server')), (file,page.pres,fences)
for file,page in parsed.items():
for target in page.links+page.sources:
url=urlsplit(target)
@@ -42,5 +44,15 @@ for file,page in parsed.items():
assert (output/'pagefind/pagefind.js').exists(), 'Missing search bundle'
for name in ['apple','notion']:
preview=output/'previews/desktop'/name/'index.html'
assert not Page(preview.read_text()).indexed
if product=='sdk': assert not Page(preview.read_text()).indexed
else: assert not preview.exists(), 'SDK previews must not appear in Desktop output'
if product=='desktop':
from zipfile import ZipFile
with ZipFile(output/'examples/meeting-notes.zip') as archive:
samples=root/'docs/desktop/samples'
expected=sorted(str(path.relative_to(samples)) for path in (samples/'meeting-notes').glob('*.md'))
assert sorted(archive.namelist())==expected, 'Unexpected sample ZIP contents'
for name in expected: assert archive.read(name)==(samples/name).read_bytes(), name
assert not (output/'examples/desktop.json').exists(), 'SDK source bundle in Desktop output'
assert not (output/'examples/web.json').exists(), 'SDK source bundle in Desktop output'
print(f'Checked {len(parsed)} Studio guides, code blocks, links, images, anchors and search assets at {base}')
+18 -17
View File
@@ -1,11 +1,12 @@
---
import {navigation} from '../lib/navigation.mjs';
import {docsProduct} from '../../product.mjs';
import SourceDrawer from '../components/SourceDrawer.astro';
import '../styles/studio.css';
const {guide,slug='index',notFound=false}=Astro.props;
const product=docsProduct(),navigation=product.navigation,isDesktop=product.id==='desktop';
const base=import.meta.env.BASE_URL.replace(/\/$/,'');
const routeSlug=slug==='index'?'':slug;
const sourceTrack=slug==='desktop'?'desktop':slug==='server'?'web':null;
const sourceTrack=isDesktop?null:slug==='desktop'?'desktop':slug==='server'?'web':null;
const group=navigation.find(group=>group.links.some(([,link])=>link===routeSlug));
const label=group?.links.find(([,link])=>link===routeSlug)?.[0]??guide.title;
const sequence=navigation.flatMap(group=>group.links);
@@ -17,47 +18,47 @@ const description=guide.subtitle.replace(/<[^>]+>/g,'').trim();
<html lang="en">
<head>
<meta charset="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>{guide.title} | OpenWorker SDK</title>
<title>{guide.title===product.title?guide.title:`${guide.title} | ${product.title}`}</title>
<meta name="description" content={description}/>
{notFound?<meta name="robots" content="noindex"/>:<link rel="canonical" href={new URL(Astro.url.pathname,Astro.site)}/>}
{notFound||isDesktop?<meta name="robots" content="noindex"/>:<link rel="canonical" href={new URL(Astro.url.pathname,Astro.site)}/>}
</head>
<body class="apple studio">
<body class:list={['apple','studio',{'product-desktop':isDesktop}]}>
<a href="#article" class="skip-link">Skip to guide</a>
<header class="masthead">
<a class="brand" href={`${base}/`} aria-label="OpenWorker documentation"><svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" transform="rotate(90 12 12)" d="M12 1.8 13.35 9.66 20.83 6.9 14.7 12l6.13 5.1-7.48-2.76L12 22.2l-1.35-7.86-7.48 2.76L9.3 12 3.17 6.9l7.48 2.76L12 1.8Z"/></svg><span>OpenWorker</span><span class="brand-divider"></span><span class="brand-docs">Developer</span></a>
<div class="header-links"><button class="search-shortcut" type="button" data-open-search aria-label="Search documentation">Search <kbd>⌘ K</kbd></button><a class="repo-link" href="https://github.com/andrewyng/openworker/tree/main/harness">GitHub <span aria-hidden="true">↗</span></a></div>
<a class="brand" href={`${base}/`} aria-label="OpenWorker documentation"><svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" transform="rotate(90 12 12)" d="M12 1.8 13.35 9.66 20.83 6.9 14.7 12l6.13 5.1-7.48-2.76L12 22.2l-1.35-7.86-7.48 2.76L9.3 12 3.17 6.9l7.48 2.76L12 1.8Z"/></svg><span>OpenWorker</span><span class="brand-divider"></span><span class="brand-docs">{isDesktop?'Desktop App':'Developer'}</span></a>
<div class="header-links"><button class="search-shortcut" type="button" data-open-search aria-label="Search documentation">Search <kbd>⌘ K</kbd></button><a class="repo-link" href={isDesktop?'https://github.com/andrewyng/openworker':'https://github.com/andrewyng/openworker/tree/main/harness'}>GitHub <span aria-hidden="true">↗</span></a></div>
</header>
<div class="docs-bar"><span>Documentation</span><button class="mobile-nav-toggle" type="button" aria-controls="docs-navigation" aria-expanded="false">Browse guides</button><a href={`${base}/`}>Harness SDK</a></div>
<div class="docs-bar"><span>Documentation</span><button class="mobile-nav-toggle" type="button" aria-controls="docs-navigation" aria-expanded="false">Browse guides</button><a href={isDesktop?'https://openworker.com/docs/sdk/':`${base}/`}>{isDesktop?'Building an app? Explore the SDK ↗':'Harness SDK'}</a></div>
<aside id="docs-navigation" class="sidebar" aria-label="Documentation navigation">
<div class="sidebar-title">Harness SDK</div>
<div class="sidebar-title">{product.label}</div>
<button class="guide-search" type="button" data-open-search><svg viewBox="0 0 20 20" aria-hidden="true"><circle cx="8.5" cy="8.5" r="5.5"/><path d="m13 13 4 4"/></svg><span>Search documentation</span></button>
<nav>{navigation.map(section=>{
const expanded=section===group;
return <details class="nav-group" open={expanded}><summary>{section.title}</summary><div>{section.links.map(([text,path])=><a href={`${base}/${path?path+'/':''}`} aria-current={path===routeSlug?'page':undefined}>{text}</a>)}</div></details>;
})}</nav>
<div class="sidebar-bottom"><a href={`${base}/`}>All documentation <span aria-hidden="true">↗</span></a></div>
<div class="sidebar-bottom"><a href={isDesktop?'https://openworker.com':`${base}/`}>{isDesktop?'openworker.com':'All documentation'} <span aria-hidden="true">↗</span></a></div>
</aside>
<main id="article" data-pagefind-body={!notFound?true:undefined}>
<section class="page-hero" aria-labelledby="guide-title">
<div class="hero-inner">
<div class="breadcrumb" data-pagefind-ignore><a href={`${base}/`}>Harness SDK</a>{slug!=='index'&&<><span aria-hidden="true">/</span><span>{group?.title}</span><span aria-hidden="true">/</span><span>{label}</span></>}</div>
<div class="breadcrumb" data-pagefind-ignore><a href={`${base}/`}>{product.label}</a>{slug!=='index'&&<><span aria-hidden="true">/</span><span>{group?.title}</span><span aria-hidden="true">/</span><span>{label}</span></>}</div>
<h1 id="guide-title" data-pagefind-meta="title">{guide.title}</h1>
{guide.subtitle&&<div class="hero-description" set:html={guide.subtitle}/>}
{sourceTrack&&<div class="hero-actions" data-pagefind-ignore><a class="primary-action" href="#build-with-your-coding-agent">Build with AI <span aria-hidden="true">↗</span></a><button type="button" class="secondary-action" data-example-source={`${base}/examples/${sourceTrack}.json`}>View example source <span aria-hidden="true">↗</span></button></div>}
{slug==='index'&&<div class="hero-actions" data-pagefind-ignore><a class="primary-action" href={`${base}/desktop/`}>Build a desktop app <span aria-hidden="true">↗</span></a><a class="secondary-action" href={`${base}/server/`}>Build a web app <span aria-hidden="true">↗</span></a></div>}
<span class="hero-motif" aria-hidden="true" data-pagefind-ignore>{'{ }'}</span>
{slug==='index'&&(isDesktop?<div class="hero-actions" data-pagefind-ignore><a class="primary-action" href={`${base}/first-task/`}>Try your first task <span aria-hidden="true">→</span></a><a class="secondary-action" href="https://download.openworker.com/mac">Download for Mac <span aria-hidden="true">↗</span></a><a class="secondary-action" href="https://download.openworker.com/windows">Windows <span aria-hidden="true">↗</span></a></div>:<div class="hero-actions" data-pagefind-ignore><a class="primary-action" href={`${base}/desktop/`}>Build a desktop app <span aria-hidden="true">↗</span></a><a class="secondary-action" href={`${base}/server/`}>Build a web app <span aria-hidden="true">↗</span></a></div>)}
{!isDesktop&&<span class="hero-motif" aria-hidden="true" data-pagefind-ignore>{'{ }'}</span>}
</div>
</section>
<div class:list={['reading-layout',{'no-contents':!guide.headings.length}]}>
<article class="guide-prose" set:html={guide.html}/>
{guide.headings.length>0&&<aside class="contents" aria-label="On this page" data-pagefind-ignore><span>On this page</span><nav>{guide.headings.map(heading=><a href={`#${heading.slug}`} data-section-link>{heading.text}</a>)}</nav></aside>}
</div>
<footer class="article-footer" data-pagefind-ignore><span>OpenWorker Harness SDK</span>{next&&<a href={`${base}/${next[1]?next[1]+'/':''}`}>Next: {next[0]} <span aria-hidden="true">→</span></a>}</footer>
<footer class="article-footer" data-pagefind-ignore><span>OpenWorker {product.label}</span>{next&&<a href={`${base}/${next[1]?next[1]+'/':''}`}>Next: {next[0]} <span aria-hidden="true">→</span></a>}</footer>
</main>
{sourceTrack&&<SourceDrawer title={sourceTrack==='desktop'?'Code Atlas':'PDF Notes'}/>}
<dialog id="docs-search" aria-label="Search documentation" data-search-base={base}>
<header class="search-header"><input type="search" placeholder="Search the SDK docs…" aria-label="Search the SDK docs" autocomplete="off"/><button type="button" data-close-search aria-label="Close search">×</button></header>
<p class="search-status" role="status">Search guides, examples and deployment instructions.</p>
<dialog id="docs-search" aria-label="Search documentation" data-search-base={base} data-search-intro={isDesktop?'Search Desktop guides and walkthroughs.':'Search guides, examples and deployment instructions.'}>
<header class="search-header"><input type="search" placeholder={isDesktop?'Search Desktop docs…':'Search the SDK docs…'} aria-label={isDesktop?'Search Desktop docs':'Search the SDK docs'} autocomplete="off"/><button type="button" data-close-search aria-label="Close search">×</button></header>
<p class="search-status" role="status">{isDesktop?'Search Desktop guides and walkthroughs.':'Search guides, examples and deployment instructions.'}</p>
<div class="search-results"></div>
</dialog>
<script>
+116
View File
@@ -0,0 +1,116 @@
export const desktopNavigation = [
{
"title": "Get started",
"links": [
[
"Overview",
""
],
[
"Your first task",
"first-task"
],
[
"How OpenWorker works",
"how-it-works"
]
]
},
{
"title": "Models and voice",
"links": [
[
"Connect a model",
"models"
],
[
"Local models",
"local-models"
],
[
"Voice and transcription",
"voice"
]
]
},
{
"title": "Work with coworkers",
"links": [
[
"Choose a coworker",
"coworkers"
],
[
"Coding coworker",
"coding"
],
[
"Conversations and files",
"sessions-files"
],
[
"Connected apps and MCP",
"connectors"
],
[
"Skills and memory",
"skills-memory"
],
[
"Automations",
"automations"
]
]
},
{
"title": "Security coworkers",
"links": [
[
"Security overview",
"security"
]
]
},
{
"title": "Machines and sandboxing",
"links": [
[
"Add a remote machine",
"machines"
],
[
"Choose where work runs",
"run-location"
],
[
"Sandbox overview",
"sandbox"
],
[
"Mac and Windows sandbox",
"native-sandbox"
],
[
"NVIDIA OpenShell",
"openshell"
]
]
},
{
"title": "Control and privacy",
"links": [
[
"Approvals and Auto-approve",
"approvals"
],
[
"Privacy and stored data",
"privacy"
],
[
"Troubleshooting",
"troubleshooting"
]
]
}
];
+2 -1
View File
@@ -1,6 +1,7 @@
---
import StudioDocs from '../layouts/StudioDocs.astro';
import {docsProduct} from '../../product.mjs';
const base=import.meta.env.BASE_URL.replace(/\/$/,'');
const guide={title:'Page not found',subtitle:'<p>This guide may have moved.</p>',headings:[],html:`<p><a href="${base}/">Return to the SDK overview</a> or search the documentation.</p>`};
const guide={title:'Page not found',subtitle:'<p>This guide may have moved.</p>',headings:[],html:`<p><a href="${base}/">Return to the ${docsProduct().label} overview</a> or search the documentation.</p>`};
---
<StudioDocs guide={guide} slug="404" notFound/>
+4 -4
View File
@@ -1,12 +1,12 @@
---
import StudioDocs from '../layouts/StudioDocs.astro';
import pages from '../../pages.json';
import {docsProduct} from '../../product.mjs';
import {renderGuide} from '../lib/render-guide.mjs';
const sources=import.meta.glob('../content/docs/*.md',{eager:true,query:'?raw',import:'default'});
const sources=import.meta.glob('../content/{docs,desktop}/*.md',{eager:true,query:'?raw',import:'default'});
export function getStaticPaths() {
return pages.map(page=>({params:{slug:page.slug==='index'?undefined:page.slug},props:{page}}));
return docsProduct().pages.map(page=>({params:{slug:page.slug==='index'?undefined:page.slug},props:{page}}));
}
const {page}=Astro.props;
const guide=await renderGuide(sources[`../content/docs/${page.slug}.md`]);
const guide=await renderGuide(sources[`../content/${docsProduct().content}/${page.slug}.md`]);
---
<StudioDocs guide={guide} slug={page.slug}/>
@@ -1,7 +1,8 @@
---
import DesktopPreview from '../../../layouts/DesktopPreview.astro';
import {docsProduct} from '../../../../product.mjs';
export function getStaticPaths() {
return ['apple','notion'].map(design=>({params:{design}}));
return docsProduct().id==='desktop'?[]:['apple','notion'].map(design=>({params:{design}}));
}
const {design}=Astro.params;
---
+3 -3
View File
@@ -14,7 +14,7 @@ if(dialog){
document.addEventListener('keydown',event=>{if((event.metaKey||event.ctrlKey)&&event.key.toLowerCase()==='k'){event.preventDefault();if(!dialog.open)open();}});
input.addEventListener('input',()=>{
clearTimeout(timer);const current=++generation,query=input.value.trim();results.replaceChildren();
if(!query){status.textContent='Search guides, examples and deployment instructions.';return;}
if(!query){status.textContent=dialog!.dataset.searchIntro??'Search guides, examples and deployment instructions.';return;}
status.textContent='Searching…';
timer=setTimeout(async()=>{
try{
@@ -23,12 +23,12 @@ if(dialog){
const response=await(await index).search(query);
const hits=await Promise.all(response.results.slice(0,12).map(result=>result.data()));
if(current!==generation||!dialog.open)return;
status.textContent=hits.length?`${response.results.length} matching ${response.results.length===1?'page':'pages'}`:'No results. Try a model, capability or deployment name.';
status.textContent=hits.length?`${response.results.length} matching ${response.results.length===1?'page':'pages'}`:'No results. Try a model, task or capability name.';
for(const hit of hits){
const url=new URL(hit.url,location.origin);
if(url.origin!==location.origin||!url.pathname.startsWith(base+'/'))continue;
const link=document.createElement('a');link.href=url.href;
const title=document.createElement('strong');title.textContent=hit.meta.title??'SDK guide';
const title=document.createElement('strong');title.textContent=hit.meta.title??'Guide';
const excerpt=document.createElement('span');excerpt.textContent=new DOMParser().parseFromString(hit.excerpt,'text/html').body.textContent;
link.append(title,excerpt);results.append(link);
}
+13
View File
@@ -53,3 +53,16 @@ button.guide-search{width:calc(100% - 8px);text-align:left;font-size:12px;color:
.search-header input::-webkit-search-cancel-button{appearance:none}
/* Preserve alignment in architecture diagrams and other literal text blocks. */
.guide-prose pre[data-language='text']{white-space:pre;overflow-wrap:normal}
/* Native captures remain untouched. Frame the useful settings content in the
article; each image link opens the full original for inspection. */
.product-desktop .app-screenshot{overflow:hidden;border:1px solid #e7e8eb;border-radius:12px;margin:28px 0 12px;aspect-ratio:1.18;background:#f4f5f7}
.product-desktop .app-screenshot p{margin:0}
.product-desktop .app-screenshot img{display:block;width:190%;max-width:none;height:auto;margin:0 0 0 -45%;border:0;border-radius:0}
.product-desktop .screenshot-voice{aspect-ratio:1.3}
.product-desktop .screenshot-machines{aspect-ratio:1.75}
.product-desktop .screenshot-coworkers{aspect-ratio:1.5}
.product-desktop .screenshot-sandbox{aspect-ratio:3.1}
.product-desktop .screenshot-auto-approve{aspect-ratio:2.75}
.product-desktop .contents nav{border:0}
.product-desktop .contents a{border:0;margin-left:0;border-radius:5px;padding-left:10px}
.product-desktop .contents a[aria-current]{background:#f0f4fa}
+52
View File
@@ -0,0 +1,52 @@
# Approvals and Auto-approve
Choose how proposed actions are reviewed before a coworker uses its tools.
Use the mode menu in the composer. **Ask for approval** is the default starting mode; check it explicitly for an existing conversation because your earlier choices and saved permissions can affect behavior.
## Understand the modes
| Mode | How to use it |
|---|---|
| Discuss | Read and discuss without edits or command execution. Use it to explore a request before acting. |
| Ask for approval | Review actions that require a decision. Reads and actions already allowed by rules can run without a new card. |
| Auto-approve | Let the automatic reviewer clear eligible actions; decisions it cannot safely clear still reach you. |
| Bypass approvals | Skip ordinary approval prompts without a reviewer. Some protected actions still require a human; this is not the same as Auto-approve. |
Available modes depend on the build and configuration. If Plan is offered, it is for read-only investigation and a proposed plan before implementation. A mode does not grant a missing connector credential or make a sandbox-denied host reachable.
## Review an approval card
Check the tool, its arguments, destination and scope. A request to write a file is different from a request to execute a script; a local change is different from sending or publishing it.
Approve an action when it matches your task. Otherwise decline it and explain what should change. If the card offers a lasting permission, consider whether you want to allow future calls too; don't select it merely to finish one task.
## Enable the automatic reviewer
In **Settings → General**, find **Auto-approve (experimental)** and enable **Auto-approve mode**. Then choose **Auto-approve** in the conversation's mode menu. Enabling the setting makes the mode available; it does not mean every conversation has switched to it.
<div class="app-screenshot screenshot-auto-approve">
[![General settings explains Enable Auto-approve mode and Shadow evaluation, with review-cost and permission-rule notes.](images/auto-approve.jpg)](images/auto-approve.jpg)
</div>
*The reviewer is enabled on this installation. The screenshot does not imply it is enabled by default.*
## How a tool call is reviewed
Permission rules first decide whether a call is allowed, blocked or needs a decision. In Auto-approve mode, an eligible call that still needs approval can be reviewed against the task, conversation and available policy context. Clear approvals can proceed; uncertainty or escalation returns control to a human. The reviewer cannot turn a rule-level block into permission.
Not every tool call needs a separate reviewer-model request. Reads or supported low-risk actions can be allowed by rules first. Model reviews add latency and model usage when they occur. The setting in the captured build uses the session model for its reviewer.
A model's verdict is a judgment, not a security guarantee. Keep the task boundaries, account permissions and [sandbox restrictions](sandbox.md) appropriate even when the reviewer is enabled.
## Try shadow evaluation
**Shadow evaluation** records what the reviewer would have decided alongside your own decision without using that verdict to approve the action. It is useful for evaluating the reviewer before relying on it, and can still incur model usage.
## When you are away
Unattended work can send pending questions and approvals to the Inbox. A parked action is waiting, not approved. Remote work also needs a connection when you return to answer it.
Review [Automations](automations.md) before expecting a scheduled task to run without interruption. Approving one action does not automatically authorize every future action or recurring run.
+35
View File
@@ -0,0 +1,35 @@
# Schedule recurring work
Turn a task you understand into work OpenWorker repeats on a schedule.
Open **Automations** in the sidebar. Start with a template or **New automation**, or ask a coworker to propose a recurring task in a conversation. Review the instructions, connections, destination and schedule before saving it.
## Start with a draft-only workflow
Try a recurring brief that saves a result in the app before adding outward actions:
```text
Every weekday morning, prepare a short summary of the project updates
available through the connections I enable. Keep the result in the
app for me to review. Don't post or send it anywhere.
```
Confirm the schedule and the actual sources. A task that posts to Slack or updates another service has a different permission scope from one that only prepares a draft.
## Review a run
Each run has a conversation you can open from the automation. Check what it read, what it produced and whether it is waiting for a question or approval. Use **Run now** for an initial test and verify the output before relying on the schedule.
Where a template offers a standing permission for a specific recurring action, read and approve that scope deliberately. Don't assume one manual approval authorizes all future runs.
## Keep the host available
Scheduled work requires the OpenWorker process on the machine hosting it to be running. A sleeping laptop is not an always-on worker. The app offers a **Keep this system awake** preference, and a [joined remote machine](machines.md) can provide a more persistent host when the task is created there.
Check the schedule displayed by the app, especially around travel or time-zone changes. A missed schedule does not imply every missed occurrence will be replayed; inspect the next run and history.
## Pause and change it
Pause an automation when its inputs, permissions or intended audience change. Review its saved instructions and delivery target before enabling it again. A successful run last week doesn't prove a changed external service or credential still works today.
For unattended decisions, review [Approvals and Auto-approve](approvals.md#when-you-are-away).
+40
View File
@@ -0,0 +1,40 @@
# Work with the coding coworker
Ask Code to explore a repository, implement a change and show how it was verified.
Enable **Code** in **Settings → Coworkers**, then choose it for a new conversation. Select the repository folder and a tool-capable model. Start with **Ask for approval** so you can review commands and edits as you learn the workflow.
## Start with a bounded change
Tell Code what should change and what a successful result looks like:
```text
In this repository, add validation for an empty display name. Follow
the existing patterns and add a regression test. Run the relevant
tests, then explain the changed files and any remaining failures.
Don't push, open a pull request or deploy anything.
```
For a larger request, ask it to inspect the project and propose a plan before making changes. A good task includes the behavior you want, constraints, a verification method and whether publishing is authorized.
## Follow the work
Review tool activity for file changes, searches, commands and test results. Dependencies may need to be installed on the machine running the session. A command's successful exit alone doesn't prove the application behaves correctly; ask for targeted tests or a preview when appropriate.
If the coworker delegates, inspect the relevant worker conversation and the lead's final verification. Several workers sharing a machine still need to coordinate directories, branches and server ports.
## Know which checkout is being edited
Check the branch and working directory before and after the task. Current Code workflows support a branch and Git worktree per task. When your build exposes **Feature worktrees** in Settings, you can configure their location, branch prefix and setup command. Older builds may use the supplied checkout directly; confirm the actual path rather than assuming worktree isolation.
A worktree is a separate checkout, not a security sandbox. It may share Git metadata with the main repository. Use a [sandbox](sandbox.md) when you need execution restrictions.
## Review before publishing
Ask for the diff, test results and any incomplete work. A local edit or commit is not a pushed branch. GitHub actions such as opening a PR need a configured connector or appropriately shared command-line login, and authorization for the target repository.
Don't paste access tokens into the conversation. If commands need a login inside a sandbox, read [native sandbox credential sharing](native-sandbox.md#share-logins-deliberately). A GitHub connector uses a different execution path from `git` or `gh` inside a sandbox.
## Work on a remote repository
For a conversation on another machine, the repository and dependencies must exist there. A path on your laptop doesn't point to the same files on the VM. Choose the machine first, then select its folder. See [Choose where work runs](run-location.md).
+38
View File
@@ -0,0 +1,38 @@
# Connect your apps and tools
Let a coworker work with the services you choose, using your accounts and permissions.
Open **Settings → Connectors** to browse available integrations. A connector supplies tools for a service; connecting an account and enabling it for a conversation are separate choices.
## Connect an account
Choose the service and follow its setup form. Some integrations offer a browser sign-in; others accept an API key or personal access token. Review the permissions requested by the service before granting access.
Signing into OpenWorker can make supported account connections easier, but it is not required for local-file work or all manually configured integrations. The available setup method depends on the service.
## Enable it for the task
In the conversation's **Access** section, check the services enabled for that session. Turning a service off there mutes it for the session; it does not disconnect the account globally.
Start with a read-oriented task:
```text
Review this week's activity in the GitHub repository I specify and
draft a short progress update here. Don't post a comment or message.
```
Review results before authorizing outward actions such as sending a message, changing an issue or creating a calendar event. Approval mode controls how proposed actions are reviewed; the connected account's own permissions still apply.
## Add tools through MCP
The Connectors settings also support custom MCP servers. Add a remote URL or the supported server JSON, test the connection and review the tools it exposes. Enable only the tools needed for your workflow.
A local MCP server command runs code on its host. Only configure servers from sources you trust, and check where credentials are stored. Tool descriptions and results from a third party are context for the agent, not permission to act outside your request.
## On another machine
Connections are machine-scoped. Check the selected machine at the top of Settings. Some connection types can be enabled or moved from another machine; others require a separate sign-in or are not transferable. Use only the actions offered by that connection's card.
Removing a local connection does not necessarily revoke a credential at the provider, or remove a copy already deployed to another machine. Review both the machine's connection list and the provider's account settings when revoking access.
See [Remote machines](machines.md) and [Privacy and stored data](privacy.md).
+54
View File
@@ -0,0 +1,54 @@
# Choose a coworker
Pick an agent whose tools and instructions fit the work you want to do.
The default **OpenWorker** coworker is a good starting point for research, analysis, documents and other daily work. Specialist coworkers bring a more focused workflow. You don't need to install a separate application for each one.
<div class="app-screenshot screenshot-coworkers">
[![The Coworkers settings screen groups the default OpenWorker, Code and security coworkers.](images/coworkers.jpg)](images/coworkers.jpg)
</div>
*Installed and enabled coworkers appear in the new-conversation picker. The screenshot shows this installation's choices, not a requirement to enable every coworker.*
## Find and enable a coworker
Open **Settings → Coworkers**. Read the description and use **Configure** to inspect its capabilities and recommended connections. Enable a coworker you want available, then select it when starting a **New session**.
| Coworker | Use it for |
|---|---|
| OpenWorker | Everyday tasks, research, analysis, scripts and deliverables |
| Code | Work in a code repository, including changes and verification |
| Security Coworker | Investigating application-code and secret findings |
| Dependency Audit Coworker | Reviewing vulnerable dependencies and focused upgrades |
| Cloud Posture Coworker | Reviewing infrastructure configuration and cloud exposure |
Availability varies by installation. An installed specialist may need to be enabled before it appears in the picker. Internal or experimental roles are not automatically part of a public release.
## Give the coworker the right context
Choose a working folder when the role requires one. Enable only the connected services needed for the task. A recommended connection explains what it unlocks; it is not consent to use every action on that service.
Start with an outcome and an explicit boundary:
```text
Compare the three proposals in this folder. Recommend one, explain the
trade-offs, and save a short decision brief. Don't contact the vendors.
```
For Code and security work, include the repository, expected result and how changes should be verified. See [Coding coworker](coding.md) and [Security coworkers](security.md).
## Delegation and teams
Some coworkers can delegate work to child agents. You may see delegated activity or linked worker conversations as part of a larger task. Team-capable roles can also coordinate through a board and staffing workflow.
These are capabilities of the selected coworker, not a requirement for every task. Review any team proposal and the access requested for its workers. Delegation does not make an agent's message equivalent to your approval.
## Install a coworker you trust
**Install a coworker** accepts supported GitHub, local-folder or ZIP sources. Inspect the role's instructions, tools, skills and requested connections before enabling it.
Coworker instructions influence an agent that can act with your granted access. Treat a third-party role as something you must trust and understand, even when its package contains instructions rather than executable plugin code.
For reusable instructions without a new role, see [Skills and memory](skills-memory.md).
+104
View File
@@ -0,0 +1,104 @@
# Create your first meeting brief
Turn three short meeting notes into a brief you can review, save and refine.
You'll ask OpenWorker to identify decisions, open questions and next steps, then save the result as `brief.md`. This task uses local files and your chosen model. You don't need to connect Slack, email or any other service.
## Set up your model
Download and open OpenWorker for [macOS](https://download.openworker.com/mac) or [Windows](https://download.openworker.com/windows).
In the initial setup, choose a model provider and connect it. If you've already opened the app, use **Settings → Models & Keys**. You can use your own cloud-provider key or a local model server, such as Ollama. A local model needs to support tool calling for this exercise.
Choose a connected model in the message composer. You can skip connecting other apps and continue without signing into an OpenWorker account for this task.
## Open the sample folder
[Download the sample meeting notes](../samples/meeting-notes.zip) and extract the ZIP on your computer. Keep the three Markdown files together in the `meeting-notes` folder. They're fictional notes created for this guide.
| File | What's in it |
|---|---|
| `01-kickoff.md` | The launch goal, scope and initial decisions |
| `02-design-review.md` | Design feedback, an accessibility concern and owners |
| `03-launch-check.md` | Readiness checks, a remaining question and next steps |
Start a **New session** with the default **OpenWorker** coworker. In the start view, select **Analyze the files in a directory**, then pick your extracted `meeting-notes` folder. Enable **Allow writing (read-write)** and choose **Add** so OpenWorker can save the brief there.
The shortcut may prefill a suggested message. Replace it with the request below. Before sending, select **Ask for approval** from the mode menu in the composer.
<details>
<summary>Already in a conversation, or don't see the shortcut?</summary>
Open the session's **Access** section, choose **Give access to a folder…**, select `meeting-notes`, enable **Allow writing (read-write)** and choose **Add**. Return to the composer and select **Ask for approval**.
Use this sample folder for the exercise so the agent has the context it needs without access to unrelated documents.
</details>
## Ask for the brief
Paste this request and send it:
```text
Read the three meeting notes in the meeting-notes folder I shared.
Create a concise brief with:
- the launch goal and decisions made;
- open questions and risks;
- next steps, with an owner and due date when the notes provide one.
Say when an owner or date is missing. Include the source filename for
each decision and next step so I can check it.
Save the result as brief.md in that same meeting-notes folder. Leave
the original notes unchanged. Ask before writing the brief, and do not
send it anywhere or connect to any other service.
```
The useful parts of this request are the **outcome**, the **source material**, the **destination** and the **boundaries**. Use the same pattern for your own tasks.
## Review the proposed action
Follow the tool activity as OpenWorker reads the notes. Reading may not need an approval card. If it asks a question, answer it in the conversation.
When a write or command needs approval, check what it will do. For this task, the intended change is a new `brief.md` inside your extracted `meeting-notes` folder. Approve the action if its path and contents match your request. If it proposes an unrelated change, decline it and explain what should change.
If no card appears, check the current mode and any saved permissions. Asking for approval in a prompt expresses your preference; the app's mode and permission rules govern how actions are reviewed.
## Check the finished file
Open `brief.md` in your `meeting-notes` folder using Finder or File Explorer. You can read a Markdown file in a text editor. A message saying “saved” is not a substitute for checking the file.
The brief should capture these details from the sample notes:
- The first release is a **read-only preview**; editing is deferred.
- **Priya** owns the keyboard-navigation fix, due **Thursday**.
- **Sam** owns the smoke test, due **Friday**.
- The support handoff still needs an owner, and the launch date is not yet confirmed.
Check the source filenames and make sure the original notes are unchanged. Wording and formatting will vary with the model you use.
## Refine it in the same session
Continue with a follow-up:
```text
Make the brief easier to scan. Put the next steps in a table, and mark
anything without an owner or due date as “Needs a decision”. Update
only brief.md in the meeting-notes folder, and ask before changing it.
```
Review the proposed edit and reopen the file. The session keeps the earlier conversation, so you can refine the work without repeating the full request.
<details>
<summary>If the task gets stuck</summary>
- **Can't send a message:** check that a provider is connected and a model is selected.
- **The notes can't be read:** check that the ZIP was extracted and the extracted folder appears in the session's Access section.
- **Writing is refused:** check that this folder has read-write access and the mode is Ask for approval, rather than Discuss or Plan.
- **The reply appears only in chat:** ask OpenWorker to save `brief.md` in the shared `meeting-notes` folder, then look for an approval request.
- **A local model describes tools but doesn't use them:** choose a tool-capable model and check its server configuration.
If you report a problem, include your operating system, app version, model/provider and a redacted error message. Never include API keys or private note contents.
</details>
+51
View File
@@ -0,0 +1,51 @@
# How OpenWorker works
Choose a coworker, give it context and work together in a conversation.
Four concepts help explain the choices you see in the app. You don't need a remote machine or a sandbox to try your [first task](first-task.md).
## Coworkers have different jobs
A **coworker** is an agent configured for a role, with instructions, tools and skills suited to that work. The default OpenWorker coworker handles everyday tasks. Code focuses on a repository. Security coworkers focus on particular kinds of investigation.
Choose the coworker when starting a conversation. Enabling a coworker makes it available in the picker; it does not give it every connected account or folder automatically. See [Choose a coworker](coworkers.md).
## A conversation is the ongoing task
A **conversation**, also called a session, holds your messages, the coworker's responses and its tool activity. A **turn** starts when you send a message and can contain several model calls and tool calls before the coworker responds or waits for you.
Continue in the same conversation to refine earlier work. Start a new one for an unrelated task or a different coworker or machine. A saved conversation gives you continuity; it doesn't mean every command that was running survives a computer restart.
## A machine is where work runs
By default, work runs on your computer. You can [add another machine](machines.md), such as a Linux VM, and choose it before starting a conversation.
The remote machine runs the agent and owns its files, conversation data and credentials. A folder on your laptop is not automatically a folder on that machine. The Desktop App lets you interact with the remote session and respond to its questions and approvals.
```text
Your Desktop App
messages · approvals · results
|
+----------+-----------+
| |
This computer Joined machine
local sessions remote sessions
local files that machine's files
| |
Optional sandbox Optional sandbox
for supported tools configured there
```
## A sandbox limits tool execution
A **sandbox** restricts supported commands and file tools using an operating-system or container boundary. It is separate from the machine choice: a remote VM is a machine, and that machine can also run sandboxed tools.
The agent loop, approvals and connectors run outside the tool sandbox. An action through a connected account is governed by that account's permissions and OpenWorker's approval rules, not by the sandbox's filesystem boundary.
Read [Sandboxing](sandbox.md) before enabling it, especially if the task needs network access or command-line logins.
## Permissions apply to actions
Folder access determines which files you share. Connected-account permissions determine what those tools can do. Approval mode determines how proposed actions are reviewed. Sandboxing adds an execution boundary.
These controls work together; none is a substitute for the others. Start with a small folder and [Ask for approval](approvals.md), then expand access deliberately as your task needs it.
Binary file not shown.

After

Width:  |  Height:  |  Size: 317 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 242 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 168 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 296 KiB

@@ -0,0 +1,24 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 310" role="img" aria-labelledby="title desc">
<title id="title">From meeting notes to a useful brief</title>
<desc id="desc">Share three notes with OpenWorker. It reads and drafts, you review the proposed write, and a brief is saved with decisions and next steps.</desc>
<defs><linearGradient id="surface" x2="1" y2="1"><stop stop-color="#f5f7fa"/><stop offset="1" stop-color="#fafbfc"/></linearGradient></defs>
<rect width="920" height="310" rx="20" fill="url(#surface)"/>
<g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" fill="#20242a">
<rect x="30" y="48" width="238" height="212" rx="12" fill="#fff" stroke="#e6e8ec"/>
<path d="M51 76h15l5 5h20v18H51z" fill="none" stroke="#737e8e" stroke-width="1.6" stroke-linejoin="round"/>
<text x="51" y="127" font-size="16" font-weight="600">Your meeting notes</text>
<g font-size="13" fill="#697180"><text x="51" y="158">01-kickoff.md</text><text x="51" y="185">02-design-review.md</text><text x="51" y="212">03-launch-check.md</text></g>
<g fill="none" stroke="#9aa5b4" stroke-width="1.5"><path d="M285 154h40m-6-6 6 6-6 6"/><path d="M595 154h40m-6-6 6 6-6 6"/></g>
<rect x="342" y="48" width="238" height="212" rx="12" fill="#fff" stroke="#dce4ee"/>
<g stroke="#506a8b" stroke-width="1.6" fill="none" stroke-linecap="round"><path d="m367 75 3 8 8 3-8 3-3 8-3-8-8-3 8-3z"/></g>
<text x="363" y="127" font-size="16" font-weight="600">OpenWorker</text>
<text x="363" y="157" font-size="13" fill="#697180">Read. Connect. Draft.</text>
<rect x="362" y="180" width="198" height="49" rx="8" fill="#f0f4f9"/>
<path d="m376 204 4 4 7-8" stroke="#526b8a" stroke-width="1.8" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
<text x="397" y="209" font-size="12" fill="#48617d">You review the action</text>
<rect x="652" y="48" width="238" height="212" rx="12" fill="#fff" stroke="#e6e8ec"/>
<path d="M675 75h15l7 7v18h-22zm15 0v8h7" fill="none" stroke="#737e8e" stroke-width="1.5" stroke-linejoin="round"/>
<text x="673" y="127" font-size="16" font-weight="600">A brief you can use</text>
<g font-size="13" fill="#697180"><text x="673" y="158">Decisions, with sources</text><text x="673" y="185">Questions and risks</text><text x="673" y="212">Next steps and owners</text></g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 2.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 134 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 224 KiB

+55
View File
@@ -0,0 +1,55 @@
# OpenWorker Desktop
Turn a request into finished work, using your files and the apps you already use.
OpenWorker runs on your computer and works with the context you share. Ask it to prepare a brief, investigate a codebase or finish a task across connected apps. It reads, uses tools and creates files while you follow its progress and decide which actions to allow.
## Start with work you already have
Give OpenWorker an outcome and the material it needs. You can start with a single folder; connected apps are optional.
![Three meeting notes flow into OpenWorker, where you review the proposed action, and become a brief with decisions, open questions and next steps.](images/notes-to-brief.svg)
- **Make sense of information.** Compare documents, pull together research and turn scattered notes into a clear recommendation.
- **Move a project forward.** Explore code, investigate a failing test or prepare changes you can review.
- **Work across your apps.** Connect services such as GitHub, Slack or your calendar, then ask for work that brings them together.
For a first try, [create a meeting brief from three sample notes](first-task.md). You'll choose a model, give access to a folder, review a proposed action and find the finished file.
## Explore the app
- [Connect a model](models.md), use [local inference](local-models.md), or [dictate requests with local transcription](voice.md).
- [Choose a coworker](coworkers.md) for everyday work, [coding](coding.md) or a [security investigation](security.md).
- [Connect your apps](connectors.md), teach a [reusable skill](skills-memory.md) or [schedule recurring work](automations.md).
- [Add a remote machine](machines.md) and [choose where a conversation runs](run-location.md).
- Review [approval modes](approvals.md), [sandboxing](sandbox.md) and [where your data goes](privacy.md).
## Give it a task, then work together
1. **Choose a model.** Connect a cloud provider with your own key, or use a model running on your hardware.
2. **Choose the context.** Share the files or connected services needed for this task.
3. **Describe the outcome.** Say what you want created, where it should go and any boundaries to follow.
4. **Review and refine.** Follow the activity, respond to approval requests and continue in the same session to improve the result.
You can return to a saved session rather than explaining the task again. Check important conclusions against the source material and open the generated files before sharing them.
## Choose how much autonomy to give
For your first task, use **Ask for approval**. Reads can happen without interrupting you; edits and commands can bring up an approval request. Review the proposed action and its arguments before allowing it. Previously saved permissions can affect when a request appears.
**Auto-approve** uses a model to review actions and passes uncertain decisions to you. It reduces interruptions, but a model's judgment is not a guarantee. You can start with manual review and change the mode when you understand the workflow.
Optional sandboxing can isolate supported commands and file tools using NVIDIA OpenShell or a supported platform sandbox. It is separate from approval mode and must be configured; choosing a folder alone does not create a sandbox.
## Use your choice of model
Set up providers in **Settings → Models & Keys**. Cloud providers need your credentials and may charge for model usage. Local model servers let you use models on your own hardware; choose one that supports tool calling for tasks that read or write files.
Your conversations and app settings are stored locally. When you use a cloud model, the task context sent to that model—including file contents the agent reads—is processed by that provider. Connected services receive the requests you make through them.
<details>
<summary>Looking to build your own AI application?</summary>
This documentation is for using the OpenWorker Desktop App. The [OpenWorker Harness SDK](https://openworker.com/docs/sdk/) is for developers building their own desktop or web applications with agents, tools and durable sessions.
</details>
+44
View File
@@ -0,0 +1,44 @@
# Run local models
Connect OpenWorker to a model server on your own hardware.
A local model server runs inference; OpenWorker supplies the agent loop and tools. For file tasks, coding or connected-app work, choose a model and server configuration that support **tool calling**. Text generation alone is not enough.
## Start with Ollama
Install and start [Ollama](https://ollama.com), then download a model suitable for your hardware and task. In **Settings → Models & Keys**, open **Ollama**, connect to the server and select an available model.
If the form offers model discovery or download, follow the controls shown there. Large downloads and larger context windows use disk space and memory; start with a model your machine can comfortably run.
Select that model in the composer and try a small task, such as reading one Markdown file and summarizing it. If it only describes a tool call instead of executing one, check the model's tool support and server settings.
## Use another local server
OpenWorker also supports several compatible servers. Choose the matching provider card when it is available in your build, or configure a compatible custom provider.
| Server | Common default address | What to check |
|---|---|---|
| llama.cpp | `http://localhost:8080` | Start `llama-server` with a suitable model and tool-capable chat template. |
| vLLM | `http://localhost:8000` | Enable automatic tool choice and the tool parser required by the model. |
| LM Studio | `http://localhost:1234` | Start its local server and load or enable the model. |
| Jan | `http://127.0.0.1:1337` | Start the Local API Server. |
| Docker Model Runner | `http://localhost:12434/engines` | Enable TCP host access and pull a model. |
| mlx-lm | `http://127.0.0.1:8080` | Start its server on Apple Silicon. Use another port if llama.cpp already uses this one. |
These are common defaults, not required ports. Enter the address your server actually uses. Supply an API key only when the server requires one.
## Balance context, memory and speed
A larger context window lets the model read more at once, but uses more memory. A longer reply limit lets it produce more output; it does not make the model faster or more capable.
Context size for servers such as llama.cpp and vLLM is set when the server starts. OpenWorker can show that value and use it for compaction, but changing an app preference cannot resize a running server's context window. LM Studio's loaded-model configuration has the same practical importance.
## A server on another computer
You can point a provider at a reachable model server on your network. That is different from [running the agent on a remote machine](machines.md): only model inference moves in this arrangement; the conversation and tools still run on the machine hosting the agent.
`localhost` always refers to the machine making the request. A remote agent pointed at `localhost:1234` looks for a server on the remote machine, not on your laptop. Use an address reachable from that machine and configure authentication and network access appropriately.
## Understand the privacy boundary
Local inference can keep model-bound context on your hardware. Tools may still access network services, and connected apps still send their requests. Review [privacy and stored data](privacy.md) before treating a workflow as fully offline.
+77
View File
@@ -0,0 +1,77 @@
# Add a remote machine
Run agents on a VM or another computer while using the Desktop App as your control surface.
A joined machine runs its own OpenWorker process and stores its conversations and files locally. It connects back to the Desktop App. You can start work there, follow the conversation and answer approvals from your laptop.
<div class="app-screenshot screenshot-machines">
[![Machines lists this computer and joined machines, with their connection status and enrollment controls.](images/machines.jpg)](images/machines.jpg)
</div>
*The captured installation has two offline test machines. A listed machine must be online before you can start or interact with its remote work.*
## Prepare the machine
Use a supported Linux or macOS machine that you control, with disk space, network access and the tools your task needs. On that machine, install the headless OpenWorker program:
```sh
curl -fsSL https://openworker.com/install.sh | sh
openworker machine status
```
The installer chooses the supported package for that system and explains any PATH or prerequisite steps. A VM subscription or cloud account is not created by this command; provision and secure the machine separately.
## Make the controller reachable
The remote machine makes an outbound connection to your Desktop App. It still needs a network path to the app's listening address. The app normally uses a loopback address, which another computer cannot reach directly.
In **Settings → Machines → Add a machine…**, follow the reachability instructions. An SSH reverse tunnel or an appropriately configured private VPN/tailnet are supported approaches. Use the actual port shown in the card; don't assume it is always 8765.
<details>
<summary>Example: an SSH reverse tunnel</summary>
If the app is using port 8765, run this on your desktop and leave it running:
```sh
ssh -N -o ServerAliveInterval=15 -R 8765:localhost:8765 you@your-machine
```
On the remote machine, the forwarded controller appears at `127.0.0.1:8765`. Adjust both sides to the port displayed by your app. A tunnel can end when either computer sleeps or reboots; it is not a substitute for persistent connectivity.
For a private VPN, follow the app's opt-in listening instructions and use the private address. Do not expose the controller directly to the public internet merely to make enrollment work.
</details>
## Enroll it
Opening **Add a machine…** creates a short-lived, one-use enrollment command. Run that command on the intended machine and verify its displayed fingerprint against `openworker machine status` there.
```sh
openworker join http://127.0.0.1:8765/j/<one-time-token> --name=my-machine
```
The command above is a shape example; copy the real command from your app. Treat it as a credential while it is valid. Don't put enrollment links in screenshots, source control or bug reports.
The card can offer **Provision with my model keys**. Leaving this selected copies credentials to the joining machine, encrypted to that machine's identity. Select it only when you trust the machine and want it to hold those credentials. You can configure access later instead.
## Give it model and tool access
The remote agent uses the remote machine's model providers. Use its **Keys** controls or select that machine in Settings to manage the connections available there. Changing a key on the laptop does not automatically rotate an already deployed copy; check the remote deployment status.
Connector transfer is capability-dependent. Some account types need their own sign-in. See [Connect your apps](connectors.md#on-another-machine).
## Keep it running
On a Linux machine, the service command configures the supported user service:
```sh
openworker machine service install
```
Check its instructions for running across logouts. On a systemd machine, user lingering may require an administrator. Keep any SSH tunnel or VPN path available as well.
An already running remote agent can continue while the Desktop App is closed. Actions waiting for your approval can still pause until you reconnect and respond. New remote requests require a working connection.
Next: [Choose where work runs](run-location.md).
+51
View File
@@ -0,0 +1,51 @@
# Connect a model
Use your choice of provider, account or compatible model server in OpenWorker.
Open **Settings → Models & Keys**. Providers are grouped into models running on your hardware, supported account subscriptions and API-key providers. Use **Search providers…** or expand the remaining providers to find yours.
<div class="app-screenshot screenshot-models">
[![Models & Keys shows local model servers, supported account connections and API-key providers.](images/models.jpg)](images/models.jpg)
</div>
*Captured in the Desktop App on macOS. Provider availability and the model list can change; open the image for a closer look.*
## Connect with an API key
1. Select your provider, such as Anthropic, OpenAI, Gemini, OpenRouter, Together or Fireworks.
2. Enter its API key in the provider's setup form. Keep keys out of conversation messages.
3. Use the test/connect action in the form and resolve any error before continuing.
4. Select the models you want available in conversations.
The provider supplies and bills model access. Connecting a key is separate from signing into an OpenWorker account. A connected provider is not a guarantee that every model it offers supports tools, images or PDFs.
## Use a supported account connection
Some provider cards let you sign in through a browser instead of pasting an API key. Follow the flow offered by that card. An account connection and an API-key connection are separate identities, even when both use the same provider.
For example, **OpenRouter account** uses the browser account flow, while **OpenRouter** accepts a key. Check the provider and account shown on the model you select. Subscription support depends on the provider and your installed build; a subscription does not imply unlimited use through every API.
## Add a custom endpoint
For a vendor or company gateway that implements a supported OpenAI-compatible API, find **Add an OpenAI-compatible provider** in the API-key group. Supply a name, the endpoint and the credential your gateway expects. Fetch the model list when the endpoint supports it, or enter its model IDs.
For Azure OpenAI, use its provider form with your resource endpoint and key. Model IDs are your Azure deployment names.
Compatibility still matters. Test both a short reply and a simple tool task before relying on a custom provider for agent work. A successful text reply alone does not prove tool calling works.
## Choose a model for a conversation
The model picker in the composer uses the models enabled in **Models & Keys**. Choose a model before sending a request. You can change the selection for subsequent messages; earlier usage remains associated with the model that produced it.
Open a model's settings to adjust the options it supports, such as **Longest reply**, thinking/effort and **Auto-compact**. Options vary by model and server. Increasing a reply limit does not increase the model's context window.
<details>
<summary>The provider is connected, but my model isn't listed</summary>
Check **Select what shows up for sessions** and use **Pick a model…** to add it. Confirm the model ID and account access. For a remote conversation, check the [remote machine's providers](run-location.md), rather than only the providers on your laptop.
</details>
Next: [Run local models](local-models.md) or [try a task with your connected model](first-task.md).
+39
View File
@@ -0,0 +1,39 @@
# Native sandboxing on Mac and Windows
Use the operating system's protections to restrict supported agent tools without a container runtime.
Choose the machine in Settings, then open **Sandbox**. The native provider available there depends on its operating system. Setup and network settings are machine-specific.
## On macOS
Choose **macOS sandbox** after enabling sandboxing. OpenWorker runs supported command and file tools under a macOS Seatbelt profile derived from the session's folders and network settings.
The profile allows the selected read-only and read-write folders, required system resources and private temporary storage. It does not grant general access to your home folder. Commands started by the runner inherit the restrictions.
Developer tools under your home directory may need to be enabled in the sandbox's toolchain settings. Network access can use an allowlist proxy; check the chosen hosts before trying package installs or Git commands. Some system/process tools are restricted even when they work in an ordinary Terminal.
## On Windows
Choose **Windows sandbox** and follow **Set up** if prompted. Its one-time setup needs administrator rights. It creates restricted local accounts and configures the filesystem and network controls used by the runner.
Commands run under a sandbox account, rather than as your normal desktop user. Session folders are explicitly granted, and the account has its own temporary area. This feature is OpenWorker's native Windows execution sandbox; it is not the Microsoft Windows Sandbox desktop application.
Review the network mode carefully. **Allow everything** permits network access while keeping the filesystem boundary. **Only the sites you allow** uses the restricted network path and proxy. Don't assume that turning the sandbox on also selected a closed network policy.
If you aren't an administrator, use the setup instructions to involve one. Don't replace a failed sandbox setup with broad permissions on your user profile.
## Share logins deliberately
In **Config & keys exposed to agents**, supported entries can make a command-line login or configuration available inside the sandbox. Examples include SSH, GitHub CLI, cloud CLI configuration or package-registry settings.
Review the source path, whether it contains credentials and which hosts the tool needs. A credential can authorize consequential actions even when the file itself is copied read-only. OpenWorker's supported sharing mechanism copies selected entries into the session's private environment; it does not mean every login in your normal account is inherited.
A browser login, OS credential store or SSH agent is not necessarily shareable as a file. A GitHub connector is a separate option: its credentials stay with the app's connector execution rather than being handed to `git` inside the sandbox.
## Check and troubleshoot
Start a new session after changing the provider or profile. If a command can't see a toolchain, check its configured path. If a host is denied, review the named destination and add only the access the task needs.
Adding folders to an existing session can require the tool environment to restart, which can lose shell state. Don't treat a background server as durable merely because the conversation remains saved.
For an alternative execution boundary, see [NVIDIA OpenShell](openshell.md).
+41
View File
@@ -0,0 +1,41 @@
# NVIDIA OpenShell integration
Run supported agent commands and file tools inside an OpenShell-managed container sandbox.
OpenWorker keeps the agent loop, model connections and approvals outside the execution container. It sends supported tool work to a runner inside the sandbox, where filesystem and network policy apply.
## Prepare the machine
Use a supported Linux host or a Mac with a working Docker Desktop setup. The Desktop App's **Settings → Sandbox** page offers OpenShell where supported and checks the required components.
Follow the setup path supplied by your OpenWorker build. OpenShell gateway, CLI and policy formats must be compatible; don't mix releases based on an unrelated SDK deployment guide. The app's checks and the errors they report are more useful than guessing a version.
On macOS, the setup may require Docker Desktop host networking and a sufficiently recent Linux kernel in Docker's VM. Enabling host networking can require a Docker restart; wait for other container work to finish first.
## Set up OpenShell
1. Open **Settings → Sandbox** on the machine that will run the work.
2. Choose OpenShell and follow its prerequisite checks and **Set up** flow.
3. Review the setup changes and image download before continuing. Allow several gigabytes of free space for container images and sandbox storage.
4. Choose the folders and network access needed by the task.
5. Start a new conversation and verify the sandbox indicator.
## How files and tools work
OpenWorker makes the session's selected folders available to the tool runner with their intended read/write grants. Other host files are not automatically present. A package or server installed in an ordinary host shell is not necessarily installed inside the container.
Shell processes execute in a Linux environment. A macOS application command or Windows executable won't become a Linux program because it was available on the controller.
Network policy restricts the container's destinations. Check the host needed by a failed Git clone, package install or web request rather than granting unrestricted internet access as the first fix.
## Approvals and connectors still apply
OpenShell does not replace OpenWorker's [approval reviewer](approvals.md). The app decides whether a tool action may proceed; the execution boundary restricts what the permitted command can reach.
Service connectors run outside the tool sandbox. Their account permissions and approval rules remain important. Don't infer that a connector is blocked merely because a shell command cannot reach the same service.
## When setup fails
Check that the container runtime and gateway are running, the required networking is enabled and disk space is available. Follow the app's reported prerequisite failure before retrying. Avoid repeated container recreation when a host prerequisite is still missing.
This page covers the Desktop App integration. Deploying a Harness SDK service cluster is a separate [developer workflow](https://openworker.com/docs/sdk/openshell/).
+45
View File
@@ -0,0 +1,45 @@
# Privacy and stored data
Understand where your work lives and which services receive it.
OpenWorker is local-first, but a workflow can still use cloud models, connected accounts, remote machines or third-party tool servers. The choices you make determine those data paths.
## Where information goes
| Information | Location or destination |
|---|---|
| Local conversations and working files | Stored on the computer running those sessions |
| Model context | Sent to the selected model provider or model server, including relevant messages, attachments and tool results |
| Connector requests | Sent to the connected service using its configured account |
| Dictation audio | Processed locally by the native transcription engine; the recording is held in memory for the operation |
| Transcribed text after you send it | Part of the conversation and its model context |
| Remote conversations and outputs | Stored on the joined machine; the Desktop App may keep a read-only cache of viewed history |
| Optional external recordings or telemetry | Sent to an export destination only when configured; review its content-capture settings |
Using a local model does not turn off connectors or shell networking. Using local transcription does not stop the resulting message from going to a cloud model when you send it.
## Credentials and account connections
Provider and connector credentials are managed through the app's local configuration and secret storage. Keep them out of prompts, screenshots and reports. Supported browser sign-ins may use OpenWorker's cloud service to broker an authorization flow; manual credential setup is available for supported integrations.
Deploying a key to a remote machine gives that machine its own copy. Encryption in transit to the machine does not mean the machine cannot use the credential after receiving it. Rotate or revoke it at the provider if the machine is no longer trusted.
Removing a connection from one machine need not revoke it at the provider or delete copies held elsewhere. Review the provider's own access controls too.
## Share files deliberately
Give access to a task-specific folder. A shared file can be read into model context, even when you marked it read-only. Read-only controls modification; it is not a confidentiality setting.
Sandboxes limit supported tool execution. The model loop and connectors operate outside them, and explicitly shared command-line credentials may be available inside. See [Sandboxing](sandbox.md).
## Memory, recordings and exports
Review saved preferences in **Settings → Memory** and remove details you don't want reused. Existing open conversations can still contain earlier context after a saved memory is changed.
If your build exposes observability or recording export, review the selected machine, destination and included fields before enabling it. Messages, tool inputs/outputs and names can contain sensitive content. Exporting a recording creates another copy governed by the destination's retention and access policies.
## Before sharing diagnostics
Remove API keys, join links, private document contents, account identifiers and sensitive paths. Logs and transcripts can include tool arguments, provider error details and file excerpts. A masked credential field does not imply the rest of an exported conversation has been redacted.
For a useful bug report, see [Troubleshooting](troubleshooting.md#report-a-problem).
+39
View File
@@ -0,0 +1,39 @@
# Choose where work runs
Select the machine before starting a conversation, then use that machine's files and models.
After you [join a machine](machines.md), the new-conversation setup row offers a **Runs on** choice. With no joined machines, that choice may be absent: work runs on your computer.
## Start a remote conversation
1. Choose **New session** and the coworker you want.
2. Set **Runs on** to the joined machine and check that it is online.
3. Choose a model available on that machine.
4. For folder-based work, select or enter a folder on the remote machine.
5. Check the access and approval mode, then send your request.
The selected machine belongs to that conversation. Opening a new conversation elsewhere doesn't move an existing session or copy its files.
## Keep the three locations straight
| Item | Which machine matters? |
|---|---|
| Repository, input files and generated outputs | The machine running the conversation |
| API keys and connected accounts used by the agent | That machine's configured connections |
| Local model endpoint | Reachable from the agent's machine; `localhost` means that machine |
| Voice dictation | The Desktop App device where you record |
| Tool sandbox | Configured on the machine running those tools |
To use a local file remotely, transfer or clone it there through an authorized workflow first. Selecting a folder on the laptop doesn't automatically mount it into the remote session.
## Follow remote work
Remote sessions appear in the app with a machine indicator. Open one to read its activity and continue the conversation. The Inbox can surface questions and approval requests from connected machines.
When a machine is offline, previously viewed conversations may remain readable as cached history. A cached transcript isn't a live connection: you cannot assume a command finished, a file changed or an approval was delivered until the machine reconnects.
## Decide between local and remote
Use your computer for quick tasks involving local documents or tools already installed there. Use another machine for a persistent development environment, Linux-specific dependencies or work that should keep running independently of your laptop.
A remote machine is not automatically a restricted environment. Configure [sandboxing](sandbox.md), network access and credentials on it just as deliberately as on your computer.
+41
View File
@@ -0,0 +1,41 @@
# Sandbox tool execution
Restrict supported commands and file tools to the environment you choose.
Open **Settings → Sandbox** for the selected machine. **Run agents in a sandbox** enables the configured provider for new sessions once its setup checks pass. Existing sessions keep their execution configuration; start a new conversation to use a changed sandbox setting.
<div class="app-screenshot screenshot-sandbox">
[![Sandbox settings provides the Run agents in a sandbox switch and explains that it applies to new sessions.](images/sandbox.jpg)](images/sandbox.jpg)
</div>
*The switch is off in this capture. Opening this page does not turn sandboxing on.*
## Choose an execution boundary
| Option | Where it fits | Setup |
|---|---|---|
| macOS sandbox | Native execution on a Mac | Uses the operating system's sandbox; no container runtime required |
| Windows sandbox | Native execution on a supported Windows PC | One-time administrator setup for restricted local accounts and network rules |
| NVIDIA OpenShell | Linux container-based execution; also usable on supported Macs with Docker | OpenShell, a working container runtime and the setup checks offered by the app |
Available choices depend on the machine and build. [Native sandboxing](native-sandbox.md) and [OpenShell setup](openshell.md) explain the differences.
## What is inside and outside
Inside the execution boundary are the supported command and file tools, the processes they start and the session folders they can access. Filesystem grants can be read-only or read-write.
The agent loop, model connections, approval system and service connectors stay outside that tool sandbox. An email connector can still send through its account if your request, its permissions and the approval rules allow it. Restricting shell networking does not disable every external connection the app can make.
## Network and credentials are explicit choices
Review allowed sites, network mode, toolchains and any shared logins. A network-open sandbox can still restrict files; an allowlist restricts destinations but does not make all allowed traffic harmless.
Model keys and connector tokens are not automatically copied into the sandbox. Credentials you deliberately share for command-line tools are an exception, and a shared folder can itself contain sensitive files. See [Share logins deliberately](native-sandbox.md#share-logins-deliberately).
## Verify a new session
After setup, start a fresh conversation and inspect its sandbox indicator. Check the folders and allowed sites. If setup cannot establish the configured boundary, resolve the error rather than silently switching to unrestricted execution.
Use [Ask for approval](approvals.md) while verifying the workflow. Sandboxing limits the tool's reach; approval review decides whether the proposed action should happen.
+40
View File
@@ -0,0 +1,40 @@
# Security coworkers
Investigate code, dependencies and infrastructure with coworkers configured for security work.
These specialists help run scanners, interpret findings in context and prepare changes for review. They complement security expertise; a clean scan or an agent's conclusion is not a guarantee that a system is secure.
## Choose the investigation
In **Settings → Coworkers**, review the Security group and enable the specialist you need. Start a new conversation with the relevant repository folder and the minimum access required.
| Coworker | Starting point | Typical result |
|---|---|---|
| Security Coworker | Application source and secret-scanning findings | Prioritized code findings and focused fixes for review |
| Dependency Audit Coworker | Dependency manifests and lockfiles | A dependency-risk assessment and minimal upgrade proposals |
| Cloud Posture Coworker | Infrastructure-as-code and, when explicitly connected, cloud read access | Evidence-backed configuration findings and proposed IaC changes |
These are the currently documented specialist roles. Availability depends on your installation; additional experimental team roles are not assumed here.
## Start with findings, not automatic remediation
```text
Review this repository for application-security risks. Run suitable
scanners if available, then triage the findings against the code.
Explain the evidence and likely impact. Don't change files, push
branches or access a live cloud account yet.
```
For dependencies, ask for the smallest upgrade that addresses the advisory and the tests needed to verify it. For cloud posture, begin with local IaC and add explicitly scoped, read-only cloud access only when needed. The Cloud Posture role is instructed to propose changes in IaC rather than apply them to live resources; use read-only credentials to enforce that boundary too.
## Review the evidence
A useful finding names the affected file or resource, the scanner or other evidence, why it matters in this project and what remains uncertain. Ask the coworker to distinguish confirmed issues from hypotheses and accepted configuration choices.
Before accepting a fix, review the diff and project tests. Don't disable a scanner rule merely to make a report look clean. Publishing a fix branch or PR is a separate action from preparing it locally.
## Control access
Use [Ask for approval](approvals.md), a task-specific folder and appropriately scoped connectors or cloud credentials. Scanner installation and execution may need network access in your [sandbox](sandbox.md).
Never paste live secrets into a prompt or a report. Findings can themselves reveal sensitive paths, code or infrastructure details; review [privacy](privacy.md) before exporting or sharing them.
+37
View File
@@ -0,0 +1,37 @@
# Conversations and files
Keep related work in one conversation and share only the files needed for it.
A conversation records messages and tool activity. The files an agent creates are separate deliverables on the machine running that conversation. Reopening a conversation restores its history; it does not make copies of every external file it referenced.
## Choose a working folder
For a folder-based coworker, select the project or workspace before starting. For everyday work, the session can have its own working area and access additional folders you share.
In **Settings → General → Files**, choose the default location for new conversations' working folders. Existing conversations keep their current folder. Changing this preference does not move old work.
## Give access to another folder
Open the conversation's **Access** section and choose **Give access to a folder…**. Select the folder and decide whether to enable **Allow writing (read-write)**. Additional folders are read-only unless you explicitly allow writing.
Use a small, task-specific folder when possible. Read-only access helps prevent edits through supported file tools; full command isolation depends on your [sandbox configuration](sandbox.md). A folder selection alone is not an operating-system sandbox.
For remote conversations, select a path on the remote machine. Local files don't appear there automatically.
## Attach context to a message
Use the composer's attachment control for supported images and files. PDF handling depends on the selected model. Some models read PDFs natively; others use the configured text-extraction or page-image fallback. Review any size or page-limit notice before sending.
Attaching a document can put its contents into model context. If you use a cloud provider, that context can leave the machine. For a large folder, letting the agent read selected files is often more useful than attaching everything.
## Find and check deliverables
Ask the coworker to name the destination file and folder. Use the file or preview controls shown in the app, or open the path in Finder or File Explorer. If a preview is unavailable, the saved file can still be inspected in its normal application.
Before sharing an output, check that the file exists, opens correctly and matches your request. For source-sensitive work, ask for filenames or references behind important claims.
## Continue or start fresh
Use the same conversation for follow-up edits and clarifications. Start a new one for a different task, coworker or machine. When context gets long, compaction can summarize older material; important decisions are worth keeping in an actual project file or brief.
For a practical example, [create and refine a meeting brief](first-task.md).
+37
View File
@@ -0,0 +1,37 @@
# Skills and memory
Teach a reusable workflow and keep the preferences you want coworkers to remember.
Skills, saved memory and conversation history solve different problems. A skill describes **how to do a task**. Memory stores useful persistent preferences. A conversation records **what happened in that task**.
## Use a skill for repeatable instructions
Open **Settings → Skills** to inspect and manage the skills available on the selected machine. A skill can describe a workflow such as preparing a weekly report, reviewing a document or following a team's writing convention.
Use the available create/install controls, or ask the coworker to help draft a skill:
```text
Help me create a weekly-status skill. Use decisions, progress, risks
and next steps as the sections. Keep the report under 300 words and
never send it automatically. Show me the instructions before saving.
```
Review the instructions and supporting files before accepting the skill. Installing instructions from a third party can steer an agent with your granted access; use sources you trust.
## Keep permissions separate
A skill does not grant an account, a folder or permission to publish. A writing skill can describe how to send a report, but the actual send still follows the conversation's authorization, tool permissions and approval mode.
The app-building skill for Codex or Claude Code is a different workflow for developers using the [Harness SDK](https://openworker.com/docs/sdk/). It is not required to use a Desktop App skill.
## Review saved memory
Open **Settings → Memory** to see stored preferences and your persistent instructions. Where enabled, **Remember new things about me** allows useful lasting details from conversations to be saved. Inspect, edit or remove entries that are wrong or no longer wanted.
Turning new saves off does not necessarily stop existing memories from being used. Remove saved entries too if you don't want them available to future conversations. Existing open conversations can retain earlier context even after a saved entry is changed.
Avoid storing credentials or other secrets as memory. A preference can become part of future model context, including context sent to a cloud provider.
## On a remote machine
Check the machine selected in Settings. Skills and memory are machine-scoped; don't assume a local edit has synchronized everywhere. Remote management support varies by feature and build. If the settings page directs you to a conversation on that machine, use that route instead of editing the laptop's settings by mistake.
+52
View File
@@ -0,0 +1,52 @@
# Troubleshooting
Start with the machine, model and permission setting involved in the failed action.
Avoid repeatedly sending a request when an earlier action may already have completed. Read the activity, check the resulting file or service state, and resolve uncertainty before retrying an action that changes something.
## Can't send or the model fails
- Open **Settings → Models & Keys** and test the provider. Check account access, model ID and any upstream error.
- Select a connected model in the composer.
- For a custom endpoint, test a short reply and a tool call; text-only compatibility isn't enough for agent tasks.
- For a remote conversation, check the providers on the remote machine.
An authentication failure is different from a rate limit or a model-response error. Don't paste a key into chat to diagnose it. See [Connect a model](models.md).
## Files can't be read or written
Check the conversation's **Access** section, the actual file path and read/write grant. A ZIP must be extracted before its contents behave like a normal folder.
On a remote machine, paths refer to that machine. In a sandbox, check the session's folder grants and toolchain configuration. If writing is blocked, check that you aren't in Discuss or Plan mode. See [Conversations and files](sessions-files.md).
## The agent is waiting
Look for an approval card, a question or an Inbox item. Auto-approve can still escalate to a human. A task waiting on a decision has not necessarily hung.
For a long command, inspect its reported status and output before starting another copy. For an offline machine, wait for the connection to return before assuming a tool failed or completed.
## A remote machine won't connect
Check the controller address and port shown by the app, the SSH tunnel or private-network route, and the machine service. An expired join command needs a fresh enrollment window, not reuse of the old token.
If the remote agent starts but cannot call a model, check its own key deployment and provider configuration. If a protocol error appears, update the older side to a compatible build. See [Remote machine setup](machines.md).
## A sandbox blocks work
Read the named prerequisite, folder or host in the error. Confirm that the runtime is running and start a new conversation after setup changes. Add narrowly scoped access for the task rather than disabling the sandbox as the first response.
OpenShell image pulls need network access and disk space. Native sandbox tools may need a shared toolchain or login that an ordinary Terminal already has. See [Sandboxing](sandbox.md).
## Voice input isn't ready
Check **Settings → Voice input**, device compatibility, microphone permission and the model's verification status. Use **Repair** for a failed model verification. See [Voice and transcription](voice.md).
## Update the app
Use **Settings → General → Check for updates** when available. Save work and review what will restart before installing. A current source feature may not yet exist in the installed build; don't use instructions for a button that isn't present without checking its availability.
## Report a problem
Include your operating system, app version, selected coworker, local or remote machine, model/provider, sandbox mode and the steps that reproduce the failure. Add the relevant error and what you expected to happen.
Use a small synthetic example when possible. Redact credentials, enrollment links, private prompts and document contents before attaching screenshots or logs. Report issues in the [OpenWorker repository](https://github.com/andrewyng/openworker/issues).
+48
View File
@@ -0,0 +1,48 @@
# Voice and local transcription
Speak a request and turn it into editable text without sending the recording to a cloud transcription service.
Open **Settings → Voice input** to check compatibility, prepare the local model and test your microphone. Voice input is a Desktop App feature; the browser-only interface does not provide the native setup controls.
<div class="app-screenshot screenshot-voice">
[![Voice input shows device compatibility, the local Whisper model and a microphone readiness test.](images/voice.jpg)](images/voice.jpg)
</div>
*This Mac already has the English voice model installed and verified. Your setup screen may offer Download instead.*
## Prepare voice input
1. Check **This device** for compatibility and any explanation shown there.
2. If the voice model is missing, select **Download** and let verification complete. The current Whisper Base English model is about 141 MiB.
3. Select **Test the microphone**. Grant microphone access through the operating system when prompted, speak a short sentence and stop the test.
4. Review the resulting text and check that the screen reports **Ready**.
On supported Apple Silicon Macs, the app can be ready without a separate download. Supported Windows builds offer a whisper.cpp model download. Intel Mac voice input is not currently supported; the device check is the authority for your machine. A downloaded model needs disk space, and transcription uses local processing resources.
## Dictate a message
Open a conversation and use the microphone control in the composer to start recording. Stop when you've finished speaking, then review the transcription in the message box. Correct names, numbers and instructions before sending it to the coworker.
Dictation prepares a normal message; it does not grant additional tools or permissions. Approval mode still applies when the coworker acts on that message.
## What stays local
The native transcription engine processes audio locally. Recordings are held in memory for the dictation operation rather than saved as an audio archive. The recognition model is kept on disk so it can be reused.
Once you **send the transcribed text**, it becomes conversation content. If that conversation uses a cloud model, the text can be sent to that provider along with the rest of the request. Local transcription and local inference are separate choices.
This feature is for dictating requests in the composer. It is not a meeting recorder or a general audio-file transcription workflow.
<details>
<summary>If voice input isn't working</summary>
- Check the device compatibility explanation and microphone permissions in system settings.
- If verification fails, use **Repair** and check available disk space and download connectivity.
- If the test reports no speech, check the selected system input device and try a short English sentence.
- If the microphone button asks you to configure voice input, return to Settings and complete the readiness test.
Avoid deleting a working model as a first troubleshooting step; it will need to be downloaded again if your build requires it.
</details>
Binary file not shown.
@@ -0,0 +1,18 @@
# Launch kickoff
Project: Fieldnotes, a fictional team knowledge app.
## Goal
Give pilot customers a simple way to read the team's shared project notes.
## Decisions
- The first release is a read-only preview.
- Editing and comments are deferred until after the pilot.
- Keep the launch date unconfirmed until readiness checks are complete.
## Next steps
- Alex will prepare the pilot invitation copy by Wednesday.
- The team still needs an owner for the support handoff.
@@ -0,0 +1,14 @@
# Design review
Project: Fieldnotes, a fictional team knowledge app.
## Feedback
- Use a short list of recent notes on the home screen.
- Keep the reading view uncluttered; no editing controls in this release.
- Keyboard focus is hard to see when moving between notes. This must be fixed before the pilot.
## Next steps
- Priya owns the keyboard-navigation and focus-state fix, due Thursday.
- Alex will check the revised invitation copy against the read-only scope by Thursday.
@@ -0,0 +1,16 @@
# Launch readiness
Project: Fieldnotes, a fictional team knowledge app.
## Status
- The read-only preview is ready for a smoke test.
- Editing is still out of scope.
- The launch date is not confirmed.
## Next steps and open questions
- Sam owns the smoke test, due Friday. Check opening notes, navigating by keyboard and returning to the home screen.
- The keyboard-navigation fix from the design review is a release blocker.
- Who will own the support handoff? No owner or due date has been assigned.
- Confirm the launch date after the smoke test and accessibility fix pass. No owner or due date has been assigned to that decision.