Developer journey

This is the red carpet from idea to a live App. Every step is paved for you — shared foundation, reference samples, AI skills, and automated review and promotion.

An App can be a custom automation (a form-driven workflow, a Factorial API job, a CSV/report export, an email notification, a scheduled task) or a marketplace integration (sync between Factorial and an external system, built on the integrations framework). The journey below is the same for both.

The journey has two phases: building the App and activating it for a customer.

For integrations, data flows in two directions:

Inbound (Pull) — a scheduled process periodically fetches data from the external system and creates or updates records in Factorial.
Outbound (Push) — a Factorial webhook fires when something happens in Factorial (e.g. a new employee is created) and the process pushes that data to the external system.

Both directions can live in the same App. Each direction is a separate process but business logic can be shared through modules.

Building the App

Request access — Developer. Fill the request-access form: contributor type and name, developer email, why you want to build on Factorial Code, and your Factorial contact. This is a one-time request to join the platform — not per App.
Get access approved — Factorial team. The team is notified and approves your request. Your development team is created and you receive an email to set up your account and sign in to the developer console.
Create an App — Developer. In the console, create a new App: its name, what it does, your language (JavaScript or Python), its type — a standard App or one built on the integrations framework, picking the data types it syncs — and the OAuth scopes it needs. For a framework App the scopes step opens with the scopes the framework and your data types need already selected. Scopes are optional — an App that doesn’t call the Factorial API needs no OAuth application, and you can add scopes later from the App’s OAuth tab. The App is provisioned automatically — no approval step — and a development workspace dev-{app-id} is created, inheriting base-app (and base-integration-app for integrations). Create as many Apps as you need this way.
Clone the workspace locally — Developer.
Terminal window
```
pnpm install -g @factorialco/fcode-cli
fcode clone dev-{app-id}
```
Clone sets up the Factorial Code AI skills by default, so your coding assistant knows the platform from the first prompt (pass --skipSkillsSetup to opt out). Base modules are available immediately: FactorialClient, fc-utils, checkWebhookChallenge, setupWebhook.
Build the App — Developer. Use your favourite AI agent — the skills carry worked examples and references, and the samples show complete Apps. Point it at the relevant material too: the Factorial platform docs and, for integrations, the external system’s API docs or specs. Build on the published SDKs for all Factorial API access.

You can also build in the console itself. The assistant in the developer console knows this platform, can see your Apps, releases, demo companies and failing runs, and will take you from an idea to an implementation plan by asking what it needs to know. When a step needs code written, it hands the work to a coding agent running in your App’s workspace — only when you ask it to. Nothing it proposes happens until you approve it.
Test locally — Developer. Run any process on your machine with fcode run {process-slug} — no deploy required. You may also build a test suite.
Push to the cloud — Developer. Sync your local workspace up to dev-{app-id} with fcode push.
Test from Factorial — Developer. Exercise the App from a Factorial demo environment, where the OAuth token is provided out of the box — no credential handling in your code (see OAuth & API token).
Request a release — Developer. Ask for a release of your development code. The requested version is published as a workspace version on your dev-{app-id} workspace — every process and module is snapshotted under that tag, with module imports pinned. The Factorial team reviews it and CI checks run automatically.
Promote to production — Factorial team, or a Factorial admin of your development team. Requesting the release created the prod-{app-id} workspace. First gate the release: run the fcode-code-validation skill on the dev workspace with your agent and don’t promote while its report has Blockers. Then push the released code into production from a fresh clone:
Terminal window
```
fcode login
fcode clone --skipSkillsSetup dev-{app-id}
cd dev-{app-id}
fcode remote:add prod-{app-id}
fcode pull
fcode add
fcode push
```
Finally the release is marked deployed, which points the stable alias at that version. Your App is now live for customers — and listed on the Factorial Marketplace. 🎉 Who may do this is a matter of roles: see Roles & permissions.

Activating it for a customer

Request the integration — Customer / Factorial admin. Submit an install form with the customer_id and the integrations to activate.
Workspace provisioned — Platform, automatic. A deploy-{installation-id} workspace is created. Repeatable — add integrations anytime.
Configure the integration — Customer / Factorial admin. Run the {vendor}-setup process and provide the credentials or configurations the app may need. On submit, this will be saved, and Factorial webhook subscriptions or schedules are created.
Integration is live — Platform, ongoing. Inbound data flows in via the scheduled poll process; outbound events flow out via the webhook-triggered push process.