Guide

The Symbiont guide, one task at a time.

The software house and its developers work in the app; the trusted stand-in uses the same app, only for the systems entrusted to them; clients use the web, without installing any software. Every task has numbered steps and a short video. The guide is organized by role.

Everything shown is fictional: the software house Ferri Digital, the client Acme Logistics, the people and every address.

For those who run the software house

Systems, team, clients and stand-ins are all managed from the app.

1

First steps: installing the app and signing in

  1. Download the app from the Download page. It is available for Mac; in beta for Windows and Linux.
  2. Open the app and sign in with your account. A software house that is new to Symbiont selects New software house? Create the account… in the sign-in window.
  3. On first sign-in, name the device and select Show QR Code; scan the code with an authenticator app (Google Authenticator, 1Password, Bitwarden or another).
  4. Enter the 6-digit code and select Verify and Turn On. Store the secret key in a safe place, as it is shown only once. From then on, every sign-in requires the code from the authenticator app.

Immediately afterwards, Prepare This Computer sets up the computer.

2

The first system: creating it and connecting its folder

  1. With File → New System…, choose the client, enter a name and, if available, the address of the repository, that is, the code archive.
  2. In This Computer, select Connect on the project folder (or drop the folder on the window). Symbiont saves in the folder a sending key that is excluded from git, the instructions for the coding assistant and, if none exists, a first description of the system.
  3. From then on, work continues as usual: the coding assistant describes the system in continuity.yaml while it builds it, and sends the description with dbc manifest push. (dbc, Symbiont's program for the terminal, is installed by the app.)
  4. For continuous integration (CI), Sending Key for CI… in the system's menu creates a key to save as a GitHub secret, with the command ready to paste.
3

The team: arrivals and departures

  1. With Team → Invite to the Team, invite a colleague as a member or as an owner. Copy the link and send it: it is shown only once and is valid for 14 days.
  2. A member works on every system and sees its description and map; keys are granted separately, from Share.
  3. Each person's computers are listed, each with its own sending key: Revoke closes one.
  4. When someone leaves the software house, select Remove: the app lists the operations performed by the platform, what remains in the vault and the keys to rotate, to be ticked off one by one.

Inviting, changing roles and removing are reserved for owners. Invitations remain listed until they are accepted and can be withdrawn.

4

Sharing a system in one click

  1. Open the system and select Share… (also available from the ⌘K search: “Share Acme TMS”).
  2. Colleagues: every member sees the description and the map. Development keys are granted with one click and fingerprint confirmation (Touch ID); production keys are authorized system by system, with a switch.
  3. Client: the people who consult the system on the web, and the emergency keys, released on request.
  4. Control: every share sends a notification to the owners and to the recipient, and every operation remains in the log. Access can be revoked at any time.
5

The client: invitation, emergency keys, log

  1. In Clients, open the client and select Invite a Person of the Client; enter the name and role (the owner or the IT contact), then select Create Invitation. The link is shown only once and is valid for 14 days; the client creates an account on the web and can consult all the documentation. The client invites its own consultants.
  2. Keys: a request for the keys from the client completes automatically at the end of the waiting period (30 days, unless the contract states otherwise).
  3. Block…: enter a reason, which the client can read, and a number of days, at most 30. A renewal requires a new reason.
  4. Emergency stand-in: the hours without an answer from the software house (48 by default) and the person who would take over. Access log: who had access to what, and when.

Only an owner can block or release the keys.

6

The trusted stand-in: appointed by the software house, confirmed by the client

  1. With Stand-ins → New Trusted Stand-in…, enter the name and email of a person outside the software house (optionally company and phone) and the systems entrusted to them. The person accepts with the link received by email, valid for 14 days.
  2. Every client of those systems sees the stand-in's name on its page and confirms the appointment, or objects with a reason: an objection appears among the software house's tasks.
  3. Every six months Symbiont asks the stand-in whether they are still available; if there is no answer, the software house is informed.
  4. When needed, select Start Stand-in…: the stand-in works in the same app, only with the systems entrusted to them. Development keys are granted from the vault; production keys only if authorized for that system.
  5. With End Now… (or on the end date), the plan becomes the list of revocations and secrets to rotate. The report can be exported to PDF.

The stand-in is not a member of the software house and does not pay.

7

Linking a system to its vault

  1. On the client's page in Clients, every system shows whether the platform can grant and withdraw access to the vault, the encrypted store of keys, automatically.
  2. Propose the vault organization and collections (prefilled from vault.ids in continuity.yaml).
  3. A platform administrator approves the link; from then on the vault-gate grants the client the Emergency collection on release, and the stand-in the Stand-in collection for the stand-in period.
  4. Once only, manually in the web vault, invite the client's and the stand-in's accounts as Users with no collections, and confirm them.
8

Security in practice

  1. The second factor. It is required for owners, members and the trusted stand-in; for clients it is optional but recommended. Two-step login should also be turned on in the vault account.
  2. The vault. Link every system to its vault and, in Team, ask each team member to enter their own vault account: the Share window then knows each person's access.
  3. Who receives which keys. Colleagues receive development keys from Share, with fingerprint confirmation. Production keys go only to those who need them, system by system. The stand-in receives keys only during the stand-in period. The client receives the emergency keys on request.
  4. When someone leaves the software house. With Team → Remove, the sending keys of the person's computers are revoked, development keys are withdrawn through the vault-gate, and production keys are marked for removal from the person's computers. Then rotate the keys on the list, one by one, and remove the person from the organization in the web vault.

The reasons for each step, and the limits, are described on the Security page.

For developers

Work continues as usual with the coding assistant; Symbiont keeps the rest in order. This section also applies to owners.

1

Prepare This Computer

  1. From This Computer (or the File menu), open Prepare This Computer: before performing any operation, it shows the base folder, the steps and the systems that can be reached.
  2. The steps then run one after another: installation of dbc, Symbiont's program for the terminal; download and connection of the systems; restoration of the development keys from the vault; connection of the coding assistant; installation of the local agent. Any step can be retried or skipped, and nothing already present is overwritten.
  3. From then on, This Computer keeps the systems' folders (Connect, Download from the Repository…, Point at the Folder…), dbc and the coding assistant in order.

From the terminal, for a server or for CI: Download → For the terminal.

2

The system's map

  1. Open the system from Systems; a double-click opens the full-screen map. With Follow Changes, every element appears while the coding assistant works; elements not yet sent are shown dashed.
  2. Elements that were added or changed are marked to confirm: review and confirm them.
  3. Elements are moved and linked by dragging; elements that the code does not show can be drawn in the same way. ⌘Z undoes the last operation.
  4. File → Export the Map produces a PNG or PDF file to show to the client.
3

Tasks

  1. To Do lists what is still missing (recovery codes, emergency keys, backups), each item with its steps.
  2. Tasks that require this computer are run by the local agent: review the plan, confirm and start it, and follow the job while it runs. The job can be cancelled.
  3. A failed check becomes a task, with the reason.
  4. The status indicator next to each system, in Systems, summarizes what remains to be done.
4

Checks: from what is declared to what is verified

  1. Verify Everything Possible… checks certificates, domains, repository access, database connections and backups from the developer's computer.
  2. Every check first states what it will do and which references it uses; the values remain in the vault.
  3. The status indicator is updated, and every result records the date and the computer that ran the check.
  4. A result is valid for 90 days; after that it returns as a task, marked “to verify again”. The client sees “verified on … by …” on its page.
5

Code and description, always aligned

  1. When the system's folder is on this computer, the app continuously compares the code with continuity.yaml. The code never leaves the computer.
  2. Elements that the code uses but that nobody has described appear in the To align group, with the file and line, and on the map as a faded element labelled “found in the code, not described”.
  3. For each difference, the available commands are Open in Your Editor, Ask the Agent to Align It, Add to the Description and Ignore.
  4. Added elements appear on the map as “not yet sent” until the description is sent.
6

Keys on the computer, without copying them by hand

  1. A system's Keys tab lists, by name, every key described in continuity.yaml and shows, environment by environment, whether it is present on this computer and in the vault.
  2. Restore the Missing Keys… writes them from the vault into the project's .env file, which is excluded from git; Save in Vault… performs the reverse operation. Certificates and keystores are dropped on the system.
  3. Run with the Keys… opens a terminal that runs a command with a value retrieved from the vault, without showing it.
  4. Production keys are granted only to the people an owner authorizes, system by system, and are removed automatically when that authorization ends.

The values never enter the app or the conversation with the coding assistant.

7

Emergencies and working without a connection

  1. Every system has its own Emergency page: where it is hosted, whom to contact and how to restore it, with the procedures from its folder. The page can be printed with Print… or saved with Export PDF….
  2. File → Export the Emergency Kit… saves one PDF per system into a folder of choice.
  3. Without a connection, the app still opens, using the encrypted copy kept on this computer; a bar shows how recent the data is. Local operations and the ⌘K search continue to work.
  4. Download Everything for Offline Use (in Settings, in the File menu or from the ⌘K search) prepares the copy before travelling.
8

Mobile apps: store accounts, signing and expiry dates

  1. For an iOS or Android app, the first description reads the bundle id or package name from the project.
  2. Add the holder of the Apple Developer or Google Play account (the client or the software house), whether Play App Signing is turned on, and the expiry dates of certificates, profiles and the Apple membership.
  3. Certificates, keystores and key files are stored in the vault and restored on a new computer together with the other keys.
  4. An expiry within 30 days generates a warning; an expiry that has passed turns the system red. An Android app without Play App Signing is reported as a problem: losing the keystore would make it impossible to update the app.

For clients

The client consults all the information about its systems on the web, without installing any software; the keys are released according to an established procedure.

1

The invitation and the documentation

  1. Open the link sent by the software house, create an account (or sign in) and select Accept.
  2. The client page shows the keys, the stand-in and the systems, each with its status indicator.
  3. Opening a system shows to whom each service is registered, emergency access, second factors, components and the checks performed, with their dates. The continuity.yaml file can be downloaded.
  4. Report opens the continuity report: summary, main risks and the plan to fix them.
2

Requesting the keys

  1. On the client page, under The keys, enter the reason and select Ask for the keys.
  2. The request completes automatically at the end of the waiting period set in the contract.
  3. If the software house has placed a reasoned block, the client can read the reason and the end date: the request waits, and a block lasts at most 30 days.
  4. Every operation is recorded in the access log, which the software house can also consult.
3

The trusted stand-in and how to request one

  1. Trusted stand-in: the client page shows the person whom the software house has appointed to stand in for it on the client's systems. The client confirms the appointment, or objects with a reason: while the objection stands, that person cannot take over.
  2. If a system is down and nobody answers, select the systems concerned, describe the problem and select Ask for a stand-in.
  3. The software house is notified and sees how many hours remain to answer.
  4. Without an answer within the waiting period (48 hours by default), the platform starts the stand-in period with the designated stand-in. The request can be withdrawn.

For the trusted stand-in

The trusted stand-in is the person whom a software house has chosen to stand in for it when needed. The stand-in uses the same app, only for the systems entrusted to them, free of charge.

1

Accepting the appointment

  1. Open the link received by email, which is valid for 14 days and only for that address, and create an account with a password.
  2. Turn on two-step sign-in, which is also required for stand-ins.
  3. Download the app from the Download page and sign in: the Stand-in page opens.
  4. Every client of the systems entrusted to the stand-in sees the stand-in's name and confirms the appointment. Every six months the app asks whether the stand-in is still available; without an answer, the software house receives a warning.
2

The stand-in period

  1. When the software house starts a stand-in period, the stand-in sees the systems concerned; until the start date, read-only.
  2. Prepare This Computer downloads and connects, with the stand-in's own git credentials, only the systems of the current stand-in period.
  3. For each access received, once it has been checked, select I have access. Each system offers Open in Terminal and Open in Editor.
  4. Development keys arrive only if an owner has granted them in the vault; production keys only if authorized for that system, and only while the stand-in period lasts.
3

At the end, the hand-back of access

  1. On the end date, or when the software house ends the stand-in period, the What to Give Back list shows the access received.
  2. Confirm each item with I no longer have access.
  3. The computer's link is revoked automatically; production keys still present must be removed, and the app shows a reminder.
  4. The software house sees the confirmations in its plan and closes the stand-in period.
The Symbiont app icon

A trial on a real system, free of charge for 30 days.

Available for Mac; in beta for Windows and Linux · 30-day free trial, no credit card required.