Docs / Build
Projects
Project spaces: settings, data, team and roles, blueprints, the workers a project may use, runs and results, and analytics.
The project space
Projects are the cards on the Projects page. Create one with a name, a description, a type and a cover (a built-in one or your own picture), and invite the colleagues who work on it. Types sort and label projects: besides the listed ones, choose Your own type… and name it (for example Drone swarms); it is then offered for the workspace's next projects. Opening a project shows its tabs:
| Tab | What it holds |
|---|---|
| Data | The datasets listed in the project and those its runs read: see Data and datasets. |
| Blueprint | The project's flows: see Blueprints. |
| Compute | Which workers and servers the project's runs may use, whether EsaSim Cloud is allowed, and what those workers are doing now. |
| Runs | Running work with its progress, and every run of the project with its flow, who started it, its tasks and its logs. |
| Results | The evidence of each run: the dataset versions it read and the files it made, browsed by block and output, with viewers for pictures, videos, tables, logs, JSON, PDF and 3D. Files left on a worker are fetched when you open them. |
| Analytics | Compute used by the project. |
| Team | Who can open the project and with which role; invitations. |
| Settings | Name, description, type and cover. |
Roles
| Role | Can |
|---|---|
| Observer | See the project, its flows, runs and results. |
| Runner | Also start and stop runs. |
| Editor | Also change the project's settings, data, flows (blocks and their code) and the compute it may use. |
| Admin | Also manage the team and delete the project. |
You can invite anyone by email, inside or outside your organization. People from outside see only that project, under Shared with you, and their runs use the compute the project allows, which belongs to the project's owner.
The readme
Every project opens on its Readme, its first tab: what the project does and how to run it, written for whoever opens it next. Write it under Settings > Readme, in Markdown (# for headings, - for lists, - [ ] for a checklist, **bold**, `code`, links, tables). Say what running it needs: the accounts and keys to paste (and in which block), the settings to fill in, the workers and accelerators, the data it reads, then the steps. Until you write one, the page is made from the project's flows: their descriptions, the keys and settings they still need, the data they read, the accelerators and packages, and the steps to run them; Write the readme starts from that page. The readme is the project's README.md on GitHub and in exports (EsaSim adds the list of its blueprint and block files after it), comes back when the project is imported or updated from GitHub, and travels with the project's templates.
The cover as a banner. The project's cover (the one chosen under Settings, built-in or your own picture) runs across the top of the Readme page, and is saved to GitHub with the project in its assets/ folder, as assets/cover.svg (a built-in cover) or assets/cover.jpg (your picture), and shown at the top of README.md, so the repository's page on GitHub opens with it too. Change the cover and the next save changes the banner. A readme with a banner picture of its own (pictures/banner, cover or hero) shows that one instead, without a second.
A readme that looks good. Write the readme starts from a template with the parts a good README has, filled in where EsaSim knows the answer and with italic prompts where only you do: a centred top with a banner, the title, a one-line tagline and badges (type, language, what it runs on, made with EsaSim); then Overview, Flows, What you need, How to run it, What you get, Data and licences (with the credits written in the blocks that download data) and Notes. Replace the prompts, delete what does not apply.
- Pictures: upload them under Data › Readme pictures (PNG, JPEG, WebP or GIF, up to 40 per project, 8 MB each; larger than 2400 px they are scaled down) and show them with
. A picture namedbanner.pngbecomes the banner of the template. They are saved with the project to GitHub and in exports aspictures/, so the README shows them there too, and they come back on import. They are pictures for the page, not data: the project's data stays on your workers. - Badges:
, the shields.io badges GitHub readmes use (a dash in a word is written--, a space%20; colours by name, likegreen, or hex, like3776AB). EsaSim draws them itself; GitHub shows them from shields.io. - Centring: as on GitHub,
<div align="center">and</div>on lines of their own centre what is between them (leave an empty line after the first).<img src="…" width="400">and<br>work too; any other HTML is shown as text.
Several projects at once
Open as many browser tabs as you like, each on a different project, even of different workspaces: each tab keeps its own project and workspace, so you can start a long run in one and go on working in another. The projects you opened recently (up to eight) are listed in the sidebar; × beside one takes it off the list. A tab running a flow shows how the run is going in its title (● 40%, ✓ done, ✕ failed, ■ stopped), so you can see it from the other tabs.
Templates
A new project can start from a template: Start from lists those included with EsaSim (a drone landing study, with a flow that renders its landings into videos, an AI data review, a Python lab) and your workspace's own. To make one, open a project's Settings and choose Save as a template: its type, cover and flows are kept (without API keys pasted in blocks), and optionally the workers it may use. Results, data and the team are not copied. Projects > Templates lists them, with the flow templates, and deletes those you no longer need.
Demos
Projects > Demos lists complete projects that EsaSim shows to every account. A demo opens like any project, with all its tabs, seen through your own workspace: you run it as it is on your workers, and its Compute, Runs, Results, Data and Analytics tabs show your workers, runs and results only (its makers see theirs, never yours). Its blueprints stay as they are: Clone into my workspace copies it into your current workspace (saved to a GitHub repository of yours) with its readme and pictures, its cover, its blueprints and the workspace blocks they use, to change as your own.
Platform admins choose the demos: open the project, then Settings > Demo for everyone. A demo stays the project of its workspace; what changes there shows on the demo page. Stop showing takes it off the list; copies already taken are not affected.
Importing a project
Projects > Import brings in a project saved to GitHub (any repository your linked GitHub account can read, with an optional folder and branch) or a zip exported from a project's Settings. Its readme, pictures, blueprints and the workspace blocks they use come in; a block that differs from this workspace's gets a new version. Choose how:
- Work on it together (pull): the project saves back to that repository and opens from it. You and everyone else with write access commit to the same repository, from this workspace or another one, and what changes on either side is merged (see Working together on GitHub). Your GitHub account needs write access. When this workspace already has a project from that repository, it opens that one: people of the same workspace work in the same project.
- Make your own copy (fork): GitHub copies the repository into your account, and the project saves to your copy. Update from the original takes in what changed in the original since, and Pull request to the original asks its people to take your changes. For a repository you can only read, or a project you want to change your own way.
- Just a copy: a project of its own, not linked to the repository.
Linking GitHub
Projects and blocks are saved to GitHub in your name, so you link your own GitHub account once, under Profile > GitHub (or from a block's or project's Save to GitHub). There are three ways; with the default A repository for each project, EsaSim makes a private repository the first time a project is saved, so the link must be allowed to make repositories as well as to write into them.
- Link GitHub (signing in with GitHub, where this EsaSim offers it): allow access to repositories when GitHub asks. Nothing else to set.
- A fine-grained personal access token (recommended among tokens): set as below.
- A classic personal access token: tick the repo scope. It reaches all your repositories, public and private.
The fine-grained token, step by step
- On GitHub: your picture › Settings › Developer settings › Personal access tokens › Fine-grained tokens › Generate new token (or Edit on an existing one).
- Resource owner: your own account. To save into an organization's repositories, choose the organization instead (its owners may have to approve the token, and allow members to make repositories).
- Expiration: a long period. When the token expires, saving stops until you link a new one.
- Repository access: All repositories. With Only select repositories the token cannot make new repositories, only write into the ones you selected.
- Permissions › Repositories: with + Add permissions, add Contents and Repository creation, and set each one's Access to Read and write. Contents saves and reads the project's files and commits (and the large files kept in the repository's releases); Repository creation makes each project's repository (on pages without it, Administration: Read and write does the same). Metadata: Read-only is added by GitHub and cannot be removed. Nothing else is needed: no account permissions, no pull requests, issues or workflows.
- Generate token (or Update), copy it (it starts with
github_pat_) and paste it in EsaSim under Profile > GitHub › Link with a personal access token. Editing the permissions of a token later keeps the same token: nothing to change in EsaSim.
When it is right, the token's page on GitHub reads, under Repository access, that it has access to all repositories owned by you, and under Repository permissions: Read and Write access to code and repository creation.
| Save to GitHub says | What to change |
|---|---|
| The token is not allowed to make repositories | Repository access on All repositories, and Repository creation (or Administration) on Read and write. Or make the repository yourself on GitHub, empty, with the name EsaSim shows, and save again. |
| GitHub does not let the token write files into the repository | Contents on Read and write; with Only select repositories, add that repository to the selection. |
| The organization does not let this link make repositories | An owner of the organization approves the token or allows members to make repositories; or save to your own account (Profile > GitHub, Owner empty). |
| Saving worked before and now fails | The token has expired: make a new one with the same settings and link it again. |
Where a project lives
Projects live on GitHub. Each one is a repository of one of its people (or a folder of a repository they chose under Profile › GitHub): its blueprints, the workspace blocks they use, its readme and pictures, its cover, its assets and its whole history. Making a project needs a linked GitHub account: New project, a template, Clone into my workspace (on a demo) and Import save it to a repository as they make it (private unless you change it on GitHub). Everyone can open the demos without one.
- What the EsaSim server keeps: each project's row (name, team, settings), its blueprints while they are edited (saved to GitHub a few seconds after each change), the history of its runs, and small results of runs (summaries and previews). Its assets are a cache: once GitHub holds an asset, the copy here may go when the cache is full (the least used first), and the first page that needs it brings it back. The project still lists it as before.
- Results of runs stay on the workers that made them and open from there: the server keeps their list. Settings › Results and cache moves them to GitHub (
results/), asks to download them when a run ends, and says when the workers clear the project's files. Settings › Hardware needed (RAM, disk, GPUs and their type) decides which workers its runs go to. - An asset is at most 1.9 GB (the most GitHub keeps in one file). Assets not saved to GitHub yet are limited per workspace (4 GB): they wait for their save before more come.
Publishing trained policies
What the blueprints make (trained policies, models, the datasets a blueprint writes) stays on your workers while the work goes on: it is not saved with every change. When you are happy with a result, publish it from the project's Data tab: Publish a version, choose the data, give it a name and notes. EsaSim fetches its files from where they are kept, zips them and makes a release of the project's repository (walk-policy-v1, then v2…) at the commit of the blueprints that made it, with your notes and where it came from. Nothing stays on the EsaSim server.
- Published on GitHub (Data tab) lists the versions, newest first, for everyone with the repository: Bring into this workspace makes the project's data <name> v<n> with its files, in a folder EsaSim may write in. On GitHub, each version's zips download from its release.
- Each zip is at most 1.9 GB; larger data goes in several. A single file larger than that cannot be published.
- The project's admins can remove a version (its release and files on GitHub); copies already brought into workspaces stay.
Assets
Data › Assets holds the files the project's views draw with: 3D models (GLB, glTF, OBJ, STL, PLY, a robot's meshes as JSON), textures and pictures, sounds, any other file, in folders of your choice (models/, textures/, audio/). Drop files or whole folders on it, or choose them; a file with the name of one already there replaces it. They belong to the project: saved with it to GitHub (under assets/; files larger than 20 MB as files of its release esasim-files), in the zip of Download the project, and taken back on import. The server keeps a copy of those in use (see Where a project lives).
The project gives its assets to its views. The 3D view draws with them, found by name: a robot's meshes (robot-spot.json, robot-h1.json), props (forklift.glb, person.glb), textures (flashlight.jpg, esacode-logo.png), a soundtrack (soundtrack.mp3), robot models (*.robot.json) when none is wired in. Replace one to change what the view shows, without changing EsaSim. The 3D view keeps its own copies only for projects that have none yet; Take the 3D view's own copies into this project (under Assets) copies those a project uses into its assets, ticked for you. A view's code reads assets with ctx.assets.find(name), then ctx.assets.buffer, text, json or url.
The project on your computer
Settings › Export makes zips on the server, then you download them. Files kept on a computer are fetched from its worker first, so it must be online; the steps of the export say which files could not be fetched. A zip stays on the server for two hours.
- Download the project: all of it, as on GitHub: readme and pictures, blueprints, the workspace blocks they use, and the files its blueprints make (trained policies), zipped inside under
files/withesasim-files.json. Projects › Import (from a zip) makes a project of it, its datasets and files included; Update from a zip brings an existing project in line with it. - Download results and policies: the files of every run of the project, a folder per run under
runs/, withruns.jsonsaying what each run was (blueprint, status, dates, the settings given for that run), and the files its blueprints make. - Load results: puts such a zip into a project, this one or another: the policies go into the project's datasets (made when missing, and the blueprints point at them), and each run comes in as an imported run of the blueprint of the same name, its files kept on EsaSim, so the Results tab shows them and they download as before. A run already in the project is skipped, so loading a zip twice adds nothing.
- Zips are sent to the server in parts, so a large one is not stopped by the server's upload limit (up to 20 GB, with twice its size free on the server's disk).
Opening a project from GitHub
A project opens from GitHub: its repository is the copy of record. Settings › Opens from shows it, and the last check.
- Saved by itself. Every change to a project opened from GitHub is saved there a few seconds after the last one: blueprints (also changes made by an AI assistant), its name, description and readme, its pictures and assets, and the workspace blocks it uses. New files its runs make (a new trained policy) are not: publish a version of them when you want. The save uses your GitHub account, or the account of whoever moved the project.
- Changes made on GitHub. When the project is opened, EsaSim asks GitHub for its last commit (at most every 30 seconds). If the repository changed elsewhere, the changes are taken in right away, files too. If the project also changed here since, the two are merged (see below); Other ways still offers Take GitHub's version or Keep this version whole.
- GitHub out of reach. The copy kept here opens, marked as such; changes are saved to GitHub once it answers.
Runs and their logs, the team, the workers a project uses and keys pasted in blocks are always kept by EsaSim; results stay on the workers that made them.
- Two saves at once. A save of a project waits for another save of it to end (Save to GitHub while a change is being saved by itself), and a save that finds the branch moved meanwhile is put on top of it.
- Assets come along. Saving a project (to GitHub, or Download the project) takes into its assets the 3D view's own files its blueprints draw with, so
assets/holds every model it uses. One you take out of the assets on purpose is not brought back.
Working together on GitHub
A project opened from GitHub works as code does in any development environment: commits, history, branches, pull requests and merges, with the project's own parts as the unit, so that a merge is made blueprint by blueprint rather than line by line in a JSON file.
- Commits. Changes are saved by themselves a few seconds after the last one, as one commit saying what changed (Trials 80; Readme changed), in the name of whoever made them, with the others who changed things in the same few seconds as co-authors. Commit in the project's header saves now, with a message of your own.
- Merges. When the project changed both here and on GitHub (a colleague in another workspace, an edit on GitHub, a merged pull request), the two are merged from the commit both started from. Blueprints are merged block by block, connection by connection and setting by setting; the readme and the code of blocks line by line; the name, description, type and cover one by one; pictures as files. What changed on one side only is taken; the same change on both sides once. Only what was changed in two different ways (the same setting set to 64 here and 128 there, the same line of the readme rewritten twice) waits for you: Choose what to keep shows each with what it was, this version and the other (and, for text, both), and nothing is saved until you finish. Moves of blocks on the canvas never clash (yours wins).
- Branches. The branch menu in the project's header (main) lists the project and its branches. Start a branch makes a working copy of the project of your own, saved to its own branch on GitHub (
esasim/<your login>/<name>): change blueprints, run them, commit, while the others keep working on main. A branch shows how far it is from main; Update from main merges in what changed there since. Branches are not listed among the projects; their runs, results and data belong to the workspace as usual (a branch uses the same datasets as the project). - Pull requests. From a branch, Open a pull request saves the branch and opens a pull request into main on GitHub, saying what changed blueprint by blueprint; the project's editors and admins with GitHub linked are asked to review it. The bar above the tabs shows it (#3 open, ✓ daniel, changes asked…). Merge into main (editors of the project) merges it here, as above, and saves it as a merge commit: GitHub shows the pull request merged. Merged on GitHub instead, main takes it in when it is opened. Then delete the branch, here and on GitHub.
- Forks. A project imported as a fork shows how far it is from the original: Update from the original merges in its new changes, and Pull request to the original sends yours; its people review and merge it on GitHub.
- History. The History tab lists the commits of the project's branch, newest first, with who made them. Open one to see what it changed: each blueprint drawn with its blocks and connections added (green), removed (red) and changed (amber), with the settings before and after; the readme and code line by line. Compare with now shows what changed since; Restore this version puts the project back as it was then, saved as a new commit, so nothing is lost.
Two people in the same workspace edit the same project directly; when both change the same blueprint at the same moment, the second is asked to reload it. For larger changes, use a branch.
Copying a project into your workspace
A project runs only on the workers of the workspace that owns it. To run someone else's project on your own hardware, copy it into your workspace: Projects › Import from its repository or from its zip (Settings › Export › Download the project). The copy is yours: it runs on your workers, and its runs and results are yours alone until you share them back: Download results and policies from your copy, and its owner uses Load results in theirs; the runs come in marked as made elsewhere.
What never comes with a copy: keys pasted in blocks (secret settings, such as an AI model's key) and data connections (drives, buckets, servers, a worker's folder). They stay with the owner's workspace; the copy shows those settings empty and asks for a connection of its own. To read the owner's data, ask them for access to it.
Starting a run
Runs start inside the project: Run in a flow's editor (the usual way), or, for the older preset jobs, New run on the Compute tab or New preset run on the Runs tab. Both show the workers the project may use and whether each is available, busy (with its free slots) or offline. Every run is also listed under Computing > Jobs, with the workspace's other jobs.
Results as folders
A run's results belong to its project: open them from the project's Results tab, by flow and run, each run with the result files of its blocks. You see only the projects your role allows: people outside the project never see its results, even if they can see the worker that produced them.