• 

• 

• 

• 

OnboardOS

AI-powered employee onboarding orchestrator built with Amazon Nova Act.

Every time a company hires someone, HR spends hours clicking through a dozen admin panels — creating accounts, assigning roles, inviting to workspaces, verifying access. OnboardOS eliminates that. HR plugs in any web-based service, authenticates once, writes what Nova should do in plain English, and hits launch. What used to take an afternoon now takes a few minutes.

---

Inspiration

We watched HR teams at growing companies repeat the same manual clicks across Jira, Slack, Google Workspace, and internal tools for every single new hire. The process is tedious, error-prone, and doesn't scale. When one admin forgets a step, the new hire shows up on day one without access to the tools they need.

We asked: what if an AI agent could just do the clicking? Not a rigid RPA script that breaks when a button moves, but an intelligent browser agent that reads the page, follows plain-English instructions, and asks a human when it's unsure.

Amazon Nova Act gave us exactly that — a purpose-built AI model for browser automation with a clean Python SDK. We built OnboardOS around it.

---

What it does

OnboardOS lets HR teams automate employee onboarding across any web-based service without writing code.

1. Add a service — Give it a name, URL, and plain-English instructions like "Invite the employee to the Engineering workspace with Member access"
2. Authenticate once — Sign in to the service's admin panel in a real browser. OnboardOS saves the session.
3. Onboard new hires — Fill in the employee details, pick which services to set up, hit launch
4. Nova does the work — For each service, Nova Act opens the admin panel with the saved session and follows the instructions
5. Human review when needed — Nova pauses and surfaces a blocker card when it needs human judgment. The operator resolves it from the dashboard.
6. Full audit trail — Every action, decision, and error is logged. Completion summaries and run history are preserved.

The system is service-agnostic. If it has a web admin panel, OnboardOS can automate it.

---

How we built it

The backend is a FastAPI application that orchestrates the entire onboarding lifecycle. When HR launches a run, the orchestrator spins up a Nova Act agent for each selected service. Each agent gets its own Chrome browser instance connected via CDP (Chrome DevTools Protocol), reusing the saved admin session. Domain guardrails keep each agent locked to its target service URL.

The frontend is a React SPA built with Vite, TanStack Router for file-based routing, and TanStack Query for server state. WebSocket connections push real-time updates from the backend so the dashboard shows live agent progress, blocker cards, and audit events without polling.

Connected services are stored in SQLite. Browser profiles (saved sessions) live on the filesystem. Active runs are held in memory for speed, with audit logs attached to each run.

The human-in-the-loop system works through callback hooks in the Nova Act SDK. When Nova encounters something that needs human judgment, it raises a blocker. The backend surfaces it as a card in the dashboard. The operator can approve, take over the browser, or skip. The resolution flows back to the agent and execution continues.

---

Challenges we ran into

• Nova Act viewport requirements — Nova Act requires a browser viewport close to 1600x813. Our initial Chrome launches used the system default window size, which caused InvalidScreenResolution errors. We had to explicitly set --window-size=1600,900 on the Chrome launch command.

• Playwright auto-install hanging — Nova Act tries to run playwright install chromium --with-deps on startup, which calls sudo apt-get and hangs indefinitely in a server process. We had to set NOVA_ACT_SKIP_PLAYWRIGHT_INSTALL=true and pre-install browsers separately.

• TTY interaction in a server context — Nova Act defaults to tty=True, which tries to read from stdin. In a background server process there's no terminal, so it blocks. Setting tty=False fixed it.

• SSL certificate errors — Some service URLs triggered SSL verification failures inside Playwright. Adding ignore_https_errors=True to the Nova Act constructor resolved it.

• Session detection — Saved browser sessions can expire. We built a session verification layer that checks whether the browser landed on a login page after restoring a session, and automatically marks the service as needing re-authentication.

• Granular prompting — Early attempts with broad instructions like "set up the employee in Jira" failed. Nova Act works best with specific, step-by-step instructions. We designed the prompt builder to combine the service instruction with structured employee data so the agent gets clear, actionable context.

---

Accomplishments that we're proud of

• Truly service-agnostic — HR can add any web service without code changes. The same system that onboards through Jira works for Slack, Google Workspace, or a custom internal tool.

• One-click session capture — The auth flow opens a real browser, lets the admin sign in normally, and saves the session. No API keys, no OAuth configuration, no service-specific integration code.

• Real browser automation in production — This isn't a mock or a demo. Nova Act drives real Chrome browsers, fills real forms, clicks real buttons, and creates real accounts.

• Human-in-the-loop that actually works — The blocker system pauses execution cleanly, surfaces context in the dashboard, and resumes after human resolution. It's not an afterthought — it's a core part of the architecture.

• Full audit visibility — Every run produces a complete timeline of what happened, what succeeded, what failed, and what the human decided. This matters for compliance and trust.

---

What we learned

• Break down instructions — Nova Act's reliability improves dramatically when you give it small, specific steps instead of broad goals. "Click the Invite button" beats "invite the user."

• Session management is hard — Browser sessions expire, cookies get invalidated, services add new auth challenges. Building robust session verification and re-auth flows was more work than expected.

• CDP is powerful but fragile — Connecting Nova Act to a persistent Chrome instance via CDP gives us session reuse and parallel execution, but browser process lifecycle management requires careful locking and cleanup.

• HR workflows are surprisingly diverse — Every company's admin panels are different. The service-agnostic approach was the right call — trying to build specific integrations for each service would never scale.

• Real-time feedback changes everything — Showing live agent progress over WebSockets makes the system feel responsive and trustworthy. Without it, HR would just be staring at a spinner wondering what's happening.

---

What's next for OnboardOS

• Amazon Bedrock AgentCore — Move browser execution to cloud-managed browser instances for scale and isolation
• Nova Act parallel execution — Run all selected services concurrently instead of serially when using saved sessions
• Smarter planning with Amazon Nova — Use a reasoning model to dynamically plan onboarding steps based on the employee's role and department
• Welcome call handoff — Use Amazon Nova Sonic to deliver a personalized welcome call to the new hire after onboarding completes
• Durable run storage — Move from in-memory to persistent run storage so runs survive backend restarts
• Screenshot persistence — Store HITL screenshots in S3 for audit and compliance
• Template marketplace — Let teams share and reuse service instruction templates across organizations

---

Built with

APIs and AI

Technology	Purpose
Amazon Nova Act SDK	AI-powered browser automation — the core agent that drives Chrome and executes onboarding steps
AWS SDK (boto3)	CloudWatch log export, S3 integration hooks, AWS service access

Backend

Technology	Purpose
Python 3.12	Backend runtime
FastAPI	REST API framework
Uvicorn	ASGI server
Pydantic	Data validation, serialization, settings management
pydantic-settings	Environment-based configuration
SQLite	Persistent storage for services, browser profiles, auth sessions
WebSockets	Real-time run updates pushed to the frontend
httpx	Async HTTP client
python-dotenv	Environment variable loading
email-validator	Email field validation
Playwright	Browser engine used by Nova Act under the hood
pytest	Backend test framework
Hypothesis	Property-based testing

Frontend

Technology	Purpose
React 18	UI framework
TypeScript	Type-safe frontend development
Vite 7	Build tool and dev server
TanStack Router	File-based routing with code splitting
TanStack Query	Server state management, caching, real-time refetch
Tailwind CSS 4	Utility-first styling
Framer Motion	Animations and transitions
React Hook Form	Form state management
Zod	Schema validation for forms
Axios	HTTP client for API calls
Lucide React	Icon library
Sonner	Toast notifications
class-variance-authority	Component variant styling
clsx + tailwind-merge	Conditional class composition
date-fns	Date formatting and utilities
Vitest	Frontend test framework
Testing Library	Component testing utilities
fast-check	Property-based testing for frontend
jsdom	DOM environment for tests

Infrastructure and tooling

Technology	Purpose
Docker Compose	Local development containerization
Chrome DevTools Protocol (CDP)	Browser process management and Nova Act connectivity
Node.js 22	Frontend build runtime
npm	Package management

Built With

• fastapi
• npm
• react